From 6b761f5fc38efdb34291b7429ccd1bff2a8ffbea Mon Sep 17 00:00:00 2001
From: gkoos <gabor.koos@gmail.com>
Date: Sat, 14 Mar 2026 03:12:53 +0000
Subject: [PATCH 1/2] Plugin architecture implemented

Circuit breaker/Deduplication refactored into plugins

Tests/docs improved
---
 README.md                                     |  46 +-
 docs/advanced.md                              |  23 +-
 docs/api.md                                   | 342 +++++--------
 docs/compatibility.md                         |   8 +-
 docs/deduplication.md                         | 102 ++--
 docs/examples.md                              |  53 +-
 docs/hooks.md                                 |  24 +-
 docs/index.md                                 |  19 +-
 docs/migration.md                             | 452 ++++--------------
 docs/plugins.md                               | 148 ++++++
 package.json                                  |  10 +
 src/circuit.ts                                |  94 ----
 src/client.ts                                 | 294 +++++-------
 src/hooks.ts                                  |   2 -
 src/index.ts                                  |  10 +-
 src/plugins.ts                                |  83 ++++
 src/plugins/circuit.ts                        | 101 ++++
 src/plugins/dedupe.ts                         | 141 ++++++
 src/timeout.ts                                |  12 -
 src/types.ts                                  |  26 +-
 test/{ => core}/client.error.test.ts          |  21 +-
 test/{ => core}/client.fetchHandler.test.ts   |   2 +-
 test/{ => core}/client.hooks.test.ts          | 123 ++++-
 test/{ => core}/client.override.test.ts       |   4 +-
 test/{ => core}/client.pending.test.ts        |   2 +-
 test/{ => core}/client.test.ts                |  62 ++-
 .../client.circuitbreaker.test.ts             | 103 ++--
 test/integration/plugins.integration.test.ts  | 123 +++++
 test/plugins/circuit.plugin.test.ts           | 120 +++++
 test/plugins/dedupe.plugin.test.ts            | 208 ++++++++
 test/{ => plugins}/dedupeRequestHash.test.ts  |   5 +-
 test/plugins/plugin.pipeline.test.ts          | 244 ++++++++++
 test/timeout.test.ts                          |  38 --
 tsup.config.ts                                |   2 +-
 34 files changed, 1884 insertions(+), 1163 deletions(-)
 create mode 100644 docs/plugins.md
 delete mode 100644 src/circuit.ts
 create mode 100644 src/plugins.ts
 create mode 100644 src/plugins/circuit.ts
 create mode 100644 src/plugins/dedupe.ts
 delete mode 100644 src/timeout.ts
 rename test/{ => core}/client.error.test.ts (95%)
 rename test/{ => core}/client.fetchHandler.test.ts (99%)
 rename test/{ => core}/client.hooks.test.ts (74%)
 rename test/{ => core}/client.override.test.ts (96%)
 rename test/{ => core}/client.pending.test.ts (99%)
 rename test/{ => core}/client.test.ts (93%)
 rename test/{ => integration}/client.circuitbreaker.test.ts (65%)
 create mode 100644 test/integration/plugins.integration.test.ts
 create mode 100644 test/plugins/circuit.plugin.test.ts
 create mode 100644 test/plugins/dedupe.plugin.test.ts
 rename test/{ => plugins}/dedupeRequestHash.test.ts (97%)
 create mode 100644 test/plugins/plugin.pipeline.test.ts
 delete mode 100644 test/timeout.test.ts

diff --git a/README.md b/README.md
index d851b26..4cffbae 100644
--- a/README.md
+++ b/README.md
@@ -15,18 +15,21 @@
 
 ffetch can wrap any fetch-compatible implementation (native fetch, node-fetch, undici, or framework-provided fetch), making it flexible for SSR, edge, and custom environments.
 
+ffetch uses a plugin architecture for optional features, so you only include what you need.
+
 **Key Features:**
 
 - **Timeouts** – per-request or global
 - **Retries** – exponential backoff + jitter
-- **Circuit breaker** – automatic failure protection
-- **Deduplication** – automatic deduping of in-flight identical requests
+- **Plugin architecture** – extensible lifecycle-based plugins for optional behavior
 - **Hooks** – logging, auth, metrics, request/response transformation
 - **Pending requests** – real-time monitoring of active requests
 - **Per-request overrides** – customize behavior on a per-request basis
 - **Universal** – Node.js, Browser, Cloudflare Workers, React Native
 - **Zero runtime deps** – ships as dual ESM/CJS
 - **Configurable error handling** – custom error types and `throwOnHttpError` flag to throw on HTTP errors
+- **Circuit breaker plugin (optional, prebuilt)** – automatic failure protection
+- **Deduplication plugin (optional, prebuilt)** – automatic deduping of in-flight identical requests
 
 ## Quick Start
 
@@ -39,13 +42,14 @@ npm install @fetchkit/ffetch
 ### Basic Usage
 
 ```typescript
-import createClient from '@fetchkit/ffetch'
+import { createClient } from '@fetchkit/ffetch'
+import { dedupePlugin } from '@fetchkit/ffetch/plugins/dedupe'
 
-// Create a client with timeout, retries, and deduplication
+// Create a client with timeout, retries, and deduplication plugin
 const api = createClient({
   timeout: 5000,
   retries: 3,
-  dedupe: true, // Enable deduplication globally
+  plugins: [dedupePlugin()],
   retryDelay: ({ attempt }) => 2 ** attempt * 100 + Math.random() * 100,
 })
 
@@ -64,7 +68,7 @@ const [r1, r2] = await Promise.all([p1, p2])
 
 ```typescript
 // Example: SvelteKit, Next.js, Nuxt, or node-fetch
-import createClient from '@fetchkit/ffetch'
+import { createClient } from '@fetchkit/ffetch'
 
 // Pass your framework's fetch implementation
 const api = createClient({
@@ -84,19 +88,31 @@ const response = await api('/api/data')
 
 ```typescript
 // Production-ready client with error handling and monitoring
+import { createClient } from '@fetchkit/ffetch'
+import { dedupePlugin } from '@fetchkit/ffetch/plugins/dedupe'
+import { circuitPlugin } from '@fetchkit/ffetch/plugins/circuit'
+
 const client = createClient({
   timeout: 10000,
   retries: 2,
-  dedupe: true,
-  dedupeHashFn: (params) => `${params.method}|${params.url}|${params.body}`,
-  circuit: { threshold: 5, reset: 30000 },
   fetchHandler: fetch, // Use custom fetch if needed
+  plugins: [
+    dedupePlugin({
+      hashFn: (params) => `${params.method}|${params.url}|${params.body}`,
+      ttl: 30_000,
+      sweepInterval: 5_000,
+    }),
+    circuitPlugin({
+      threshold: 5,
+      reset: 30_000,
+      onCircuitOpen: (req) => console.warn('Circuit opened due to:', req.url),
+      onCircuitClose: (req) => console.info('Circuit closed after:', req.url),
+    }),
+  ],
   hooks: {
     before: async (req) => console.log('→', req.url),
     after: async (req, res) => console.log('←', res.status),
     onError: async (req, err) => console.error('Error:', err.message),
-    onCircuitOpen: (req) => console.warn('Circuit opened due to:', req.url),
-    onCircuitClose: (req) => console.info('Circuit closed after:', req.url),
   },
 })
 
@@ -130,6 +146,7 @@ Native `fetch`'s controversial behavior of not throwing errors for HTTP error st
 | --------------------------------------------- | ------------------------------------------------------------------------- |
 | **[Complete Documentation](./docs/index.md)** | **Start here** - Documentation index and overview                         |
 | **[API Reference](./docs/api.md)**            | Complete API documentation and configuration options                      |
+| **[Plugin Architecture](./docs/plugins.md)**  | Plugin lifecycle, custom plugin authoring, and integration patterns       |
 | **[Deduplication](./docs/deduplication.md)**  | How deduplication works, hash config, optional TTL cleanup, limitations   |
 | **[Error Handling](./docs/errorhandling.md)** | Strategies for managing errors, including `throwOnHttpError`              |
 | **[Advanced Features](./docs/advanced.md)**   | Per-request overrides, pending requests, circuit breakers, custom errors  |
@@ -161,7 +178,7 @@ npm install abort-controller-x
 
 ```html
 <script type="module">
-  import createClient from 'https://unpkg.com/@fetchkit/ffetch/dist/index.min.js'
+  import { createClient } from 'https://unpkg.com/@fetchkit/ffetch/dist/index.min.js'
 
   const api = createClient({ timeout: 5000 })
   const data = await api('/api/data').then((r) => r.json())
@@ -170,9 +187,9 @@ npm install abort-controller-x
 
 ## Deduplication Limitations
 
-- Deduplication is **off** by default. Enable it via the `dedupe` option.
+- Deduplication is **off** by default. Enable it via `plugins: [dedupePlugin()]`.
 - The default hash function is `dedupeRequestHash`, which handles common body types and skips deduplication for streams and FormData.
-- Optional stale-entry cleanup: `dedupeTTL` enables map-entry eviction, and `dedupeSweepInterval` controls how often eviction runs. TTL eviction only removes dedupe keys; it does not reject already in-flight promises.
+- Optional stale-entry cleanup: `dedupePlugin({ ttl, sweepInterval })` enables map-entry eviction. TTL eviction only removes dedupe keys; it does not reject already in-flight promises.
 - **Stream bodies** (`ReadableStream`, `FormData`): Deduplication is skipped for requests with these body types, as they cannot be reliably hashed or replayed.
 - **Non-idempotent requests**: Use deduplication with caution for non-idempotent methods (e.g., POST), as it may suppress multiple intended requests.
 - **Custom hash function**: Ensure your hash function uniquely identifies requests to avoid accidental deduplication.
@@ -185,6 +202,7 @@ See [deduplication.md](./docs/deduplication.md) for full details.
 | -------------------- | ------------------------- | -------------------- | -------------------------------------------------------------------------------------- |
 | Timeouts             | ❌ Manual AbortController | ✅ Built-in          | ✅ Built-in with fallbacks                                                             |
 | Retries              | ❌ Manual implementation  | ❌ Manual or plugins | ✅ Smart exponential backoff                                                           |
+| Plugin Architecture  | ❌ Not available          | ⚠️ Interceptors only | ✅ First-class plugin pipeline (optional built-in + custom plugins)                    |
 | Circuit Breaker      | ❌ Not available          | ❌ Manual or plugins | ✅ Automatic failure protection                                                        |
 | Deduplication        | ❌ Not available          | ❌ Not available     | ✅ Automatic deduplication of in-flight identical requests                             |
 | Request Monitoring   | ❌ Manual tracking        | ❌ Manual tracking   | ✅ Built-in pending requests                                                           |
diff --git a/docs/advanced.md b/docs/advanced.md
index 6cd4cce..2c53a28 100644
--- a/docs/advanced.md
+++ b/docs/advanced.md
@@ -209,12 +209,17 @@ This is useful for:
 ### Configuration
 
 ```typescript
+import { createClient } from '@fetchkit/ffetch'
+import { circuitPlugin } from '@fetchkit/ffetch/plugins/circuit'
+
 const client = createClient({
   retries: 0, // let circuit breaker handle failures
-  circuit: {
-    threshold: 5, // Open after 5 consecutive failures
-    reset: 30_000, // Close after 30 seconds
-  },
+  plugins: [
+    circuitPlugin({
+      threshold: 5, // Open after 5 consecutive failures
+      reset: 30_000, // Close after 30 seconds
+    }),
+  ],
 })
 ```
 
@@ -227,12 +232,15 @@ const client = createClient({
 
 ```typescript
 // Different thresholds for different endpoints
+import { createClient } from '@fetchkit/ffetch'
+import { circuitPlugin } from '@fetchkit/ffetch/plugins/circuit'
+
 const apiClient = createClient({
-  circuit: { threshold: 10, reset: 60_000 }, // More tolerant for API
+  plugins: [circuitPlugin({ threshold: 10, reset: 60_000 })], // More tolerant for API
 })
 
 const healthClient = createClient({
-  circuit: { threshold: 3, reset: 10_000 }, // Less tolerant for health checks
+  plugins: [circuitPlugin({ threshold: 3, reset: 10_000 })], // Less tolerant for health checks
 })
 ```
 
@@ -256,7 +264,8 @@ const healthClient = createClient({
 ### Error Handling Example
 
 ```typescript
-import createClient, {
+import {
+  createClient,
   TimeoutError,
   AbortError,
   CircuitOpenError,
diff --git a/docs/api.md b/docs/api.md
index 0d08c89..a5505c0 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1,284 +1,168 @@
 # API Reference
 
-## createClient(options?)
+## Imports
 
-Creates a new HTTP client instance with the specified configuration. You can use ffetch as a drop-in replacement for native fetch, or wrap any fetch-compatible implementation (e.g., node-fetch, undici, SvelteKit/Next.js/Nuxt-provided fetch) for SSR, edge, and custom environments.
+`@fetchkit/ffetch` now exports named symbols only.
 
 ```typescript
-import createClient from '@fetchkit/ffetch'
-
-const client = createClient({
-  timeout: 5000,
-  retries: 3,
-  throwOnHttpError: true, // <-- Throws HttpError for 4xx/5xx/429 after all retries
-  // ... other options
-})
-
-// Example: throwOnHttpError usage
-const clientStrict = createClient({ throwOnHttpError: true })
-// Throws HttpError for 404, 500, 429, etc.
-await clientStrict('https://example.com/404') // throws
+import { createClient } from '@fetchkit/ffetch'
 ```
 
-### Configuration Options
-
-| Option                | Type                                                                                                                      | Default                             | Description                                                                                                                                             |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `timeout`             | `number` (ms)                                                                                                             | `5000`                              | Whole-request timeout in milliseconds. Use `0` to disable timeout                                                                                       |
-| `retries`             | `number`                                                                                                                  | `0`                                 | Maximum retry attempts                                                                                                                                  |
-| `retryDelay`          | `number \| (ctx: { attempt, request, response, error }) => number`                                                        | Exponential backoff + jitter        | Delay between retries                                                                                                                                   |
-| `shouldRetry`         | `(ctx: { attempt, request, response, error }) => boolean`                                                                 | Retries on network errors, 5xx, 429 | Custom retry logic                                                                                                                                      |
-| `dedupe`              | `boolean`                                                                                                                 | `false`                             | If true, enables automatic deduplication of in-flight identical requests.                                                                               |
-| `dedupeHashFn`        | `(params: DedupeHashParams) => string \| undefined`                                                                       | `dedupeRequestHash`                 | Custom function to generate deduplication keys. Return `undefined` to skip deduplication for a request.                                                 |
-| `dedupeTTL`           | `number` (ms)                                                                                                             | `undefined`                         | Optional TTL for dedupe-map entries. Expired entries are evicted by the sweeper.                                                                        |
-| `dedupeSweepInterval` | `number` (ms)                                                                                                             | `5000`                              | Interval used by the dedupe sweeper when `dedupeTTL` is set.                                                                                            |
-| `throwOnHttpError`    | `boolean`                                                                                                                 | `false`                             | If true, throws an `HttpError` for all HTTP error responses (all 4xx and 5xx) after all retries are exhausted. Otherwise, returns the final `Response`. |
-| `circuit`             | `{ threshold: number, reset: number }`                                                                                    | `undefined`                         | Circuit-breaker configuration                                                                                                                           |
-| `hooks`               | `{ before, after, onError, onRetry, onTimeout, onAbort, onCircuitOpen, onComplete, transformRequest, transformResponse }` | `{}`                                | Lifecycle hooks and transformers                                                                                                                        |
-| `fetchHandler`        | `(input: RequestInfo \| URL, init?: RequestInit) => Promise<Response>`                                                    | `global fetch`                      | Custom fetch-compatible implementation to wrap (e.g., SvelteKit, Next.js, Nuxt, node-fetch, undici, or any polyfill). Defaults to global fetch.         |
-
-### Deduplication
+Feature plugins are exported from subpath entrypoints:
 
-#### `dedupe` (boolean)
-
-Enable automatic deduplication of in-flight identical requests. When enabled, requests with the same deduplication key will share a single network call and response promise.
+```typescript
+import {
+  dedupePlugin,
+  dedupeRequestHash,
+} from '@fetchkit/ffetch/plugins/dedupe'
+import { circuitPlugin } from '@fetchkit/ffetch/plugins/circuit'
+```
 
-#### `dedupeHashFn` (function)
+Custom plugin authoring is documented in [plugins.md](./plugins.md).
 
-Custom function to generate deduplication keys. Receives a `DedupeHashParams` object (exported from the package) and should return a string key or `undefined` to skip deduplication.
+## createClient(options?)
 
-**Type:**
+Creates a new HTTP client instance.
 
 ```typescript
-import type { DedupeHashParams } from '@fetchkit/ffetch'
+import { createClient } from '@fetchkit/ffetch'
+
 const client = createClient({
-  dedupe: true,
-  dedupeHashFn: (params: DedupeHashParams) =>
-    `${params.method}|${params.url}|${params.body}`,
+  timeout: 5000,
+  retries: 2,
+  throwOnHttpError: true,
 })
 ```
 
-**Default:**
-Uses the built-in `dedupeRequestHash` function, which considers method, URL, and body, and skips deduplication for FormData and ReadableStream bodies.
-
-#### `dedupeTTL` (number, milliseconds)
-
-Optional TTL for dedupe-map entries. If set, expired entries are removed by a sweeper timer. This helps prevent stale in-flight dedupe keys from lingering indefinitely in failure or hanging-request scenarios.
-
-Important behavior:
-
-- Deduplication still works when `dedupeTTL` is `undefined`.
-- TTL eviction only removes dedupe keys from the map.
-- TTL eviction does **not** reject already in-flight promises.
-
-#### `dedupeSweepInterval` (number, milliseconds)
+### Core Options
 
-Controls how often the dedupe sweeper checks for expired entries when `dedupeTTL` is enabled.
+| Option             | Type                                                                                                       | Default                             | Description                                                                           |
+| ------------------ | ---------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------- |
+| `timeout`          | `number` (ms)                                                                                              | `5000`                              | Whole-request timeout in milliseconds. Use `0` to disable timeout.                    |
+| `retries`          | `number`                                                                                                   | `0`                                 | Maximum retry attempts.                                                               |
+| `retryDelay`       | `number \| (ctx: { attempt, request, response, error }) => number`                                         | Exponential backoff + jitter        | Delay between retries.                                                                |
+| `shouldRetry`      | `(ctx: { attempt, request, response, error }) => boolean`                                                  | Retries on network errors, 5xx, 429 | Custom retry logic.                                                                   |
+| `throwOnHttpError` | `boolean`                                                                                                  | `false`                             | If true, throws an `HttpError` for 4xx/5xx/429 after retries are exhausted.           |
+| `hooks`            | `{ before, after, onError, onRetry, onTimeout, onAbort, onComplete, transformRequest, transformResponse }` | `{}`                                | Lifecycle hooks and transformers.                                                     |
+| `fetchHandler`     | `(input: RequestInfo \| URL, init?: RequestInit) => Promise<Response>`                                     | `global fetch`                      | Custom fetch-compatible implementation to wrap.                                       |
+| `plugins`          | `ClientPlugin[]`                                                                                           | `[]`                                | Optional plugin list. Use this for dedupe, circuit breaker, and third-party features. |
 
-- Default: `5000` ms.
-- Only relevant when `dedupeTTL` is set to a positive number.
+### Plugin Features
 
-**Limitations:**
-
-- Deduplication is off by default.
-- Stream bodies (`ReadableStream`, `FormData`) are not deduped.
-- Use with caution for non-idempotent requests (e.g., POST).
-- Ensure your custom hash function uniquely identifies requests to avoid accidental deduplication.
-
-See [deduplication.md](./deduplication.md) for full details.
-
-### Type Exports
-
-The following types are exported for custom configuration:
-
-- `DedupeHashParams` (for custom dedupe hash functions)
-
-### Return Type
-
-```typescript
-type FFetch = (
-  input: RequestInfo | URL,
-  init?: RequestInit & {
-    // Per-request overrides for any client option
-    timeout?: number
-    retries?: number
-    retryDelay?: number | ((ctx: RetryContext) => number)
-    shouldRetry?: (ctx: RetryContext) => boolean
-    dedupe?: boolean
-    dedupeHashFn?: (params: DedupeHashParams) => string | undefined
-    dedupeTTL?: number
-    dedupeSweepInterval?: number
-    throwOnHttpError?: boolean
-    circuit?: { threshold: number; reset: number }
-    hooks?: HooksConfig
-    fetchHandler?: (
-      input: RequestInfo | URL,
-      init?: RequestInit
-    ) => Promise<Response>
-  }
-) => Promise<Response>
-```
-
-The returned function also has a `pendingRequests` property:
+#### Deduplication Plugin
 
 ```typescript
-client.pendingRequests: PendingRequest[]
-```
+import { createClient } from '@fetchkit/ffetch'
+import { dedupePlugin } from '@fetchkit/ffetch/plugins/dedupe'
 
-Where `PendingRequest` is:
-
-```typescript
-interface PendingRequest {
-  promise: Promise<Response>
-  request: Request
-  controller: AbortController
-}
+const client = createClient({
+  plugins: [
+    dedupePlugin({
+      hashFn: (params) => `${params.method}|${params.url}|${params.body}`,
+      ttl: 30_000,
+      sweepInterval: 5_000,
+    }),
+  ],
+})
 ```
 
-The client also exposes an `abortAll()` helper:
+#### Circuit Breaker Plugin
 
 ```typescript
-client.abortAll(): void // Aborts all currently pending requests
-```
+import { createClient } from '@fetchkit/ffetch'
+import { circuitPlugin } from '@fetchkit/ffetch/plugins/circuit'
 
-### Circuit Breaker State
-
-#### client.circuitOpen
-
-`circuitOpen: boolean` — True if the circuit breaker is open (blocking requests), false otherwise.
-
-> **Note:** If the client is not configured with a circuit breaker, `client.circuitOpen` will always be `false`.
-
-This property allows you to check if the client is currently blocking requests due to repeated failures. It is useful for monitoring, debugging, or custom logic:
+const client = createClient({
+  plugins: [
+    circuitPlugin({
+      threshold: 5,
+      reset: 30_000,
+      onCircuitOpen: (req) => console.warn('Circuit opened:', req.url),
+      onCircuitClose: (req) => console.info('Circuit closed:', req.url),
+    }),
+  ],
+})
 
-```typescript
 if (client.circuitOpen) {
-  console.warn('Circuit breaker is open, requests are blocked.')
+  console.warn('Circuit breaker is open')
 }
 ```
 
-### Default Values
+### Custom Plugins
 
-| Option                | Default Value / Logic                                                                            |
-| --------------------- | ------------------------------------------------------------------------------------------------ |
-| `timeout`             | `5000` ms (5 seconds)                                                                            |
-| `retries`             | `0` (no retries)                                                                                 |
-| `retryDelay`          | Exponential backoff + jitter: `({ attempt }) => 2 ** attempt * 200 + Math.random() * 100`        |
-| `shouldRetry`         | Retries on network errors, HTTP 5xx, or 429. Does not retry on 4xx (except 429) or abort/timeout |
-| `dedupe`              | `false`                                                                                          |
-| `dedupeHashFn`        | `dedupeRequestHash`                                                                              |
-| `dedupeTTL`           | `undefined` (disabled)                                                                           |
-| `dedupeSweepInterval` | `5000` ms                                                                                        |
-| `circuit`             | `undefined` (circuit breaker disabled by default)                                                |
-| `hooks`               | `{}` (no hooks by default)                                                                       |
-
-### Notes
-
-- Signal combination (user, timeout, transformRequest) requires `AbortSignal.any`. If your environment does not support it, you must install a polyfill before using ffetch.
-- The first retry attempt uses `attempt = 2` (i.e., the first call is attempt 1, first retry is 2)
-- `shouldRetry` default logic: retries on network errors, HTTP 5xx, or 429; does not retry on 4xx (except 429), abort, or timeout errors
-- All client options can be overridden on a per-request basis via the `init` parameter
-
-### Type Definitions
+Use the public plugin types from the root package and register your plugins via `plugins`.
 
 ```typescript
-interface RetryContext {
-  attempt: number
-  request: Request
-  response?: Response
-  error?: unknown
-}
-
-interface HooksConfig {
-  before?: (req: Request) => Promise<void> | void
-  after?: (req: Request, res: Response) => Promise<void> | void
-  onError?: (req: Request, err: unknown) => Promise<void> | void
-  onRetry?: (
-    req: Request,
-    attempt: number,
-    err?: unknown,
-    res?: Response
-  ) => Promise<void> | void
-  onTimeout?: (req: Request) => Promise<void> | void
-  onAbort?: (req: Request) => Promise<void> | void
-  onCircuitOpen?: (req: Request) => Promise<void> | void
-  onComplete?: (
-    req: Request,
-    res?: Response,
-    err?: unknown
-  ) => Promise<void> | void
-  transformRequest?: (req: Request) => Promise<Request> | Request
-  transformResponse?: (
-    res: Response,
-    req: Request
-  ) => Promise<Response> | Response
+import { createClient, type ClientPlugin } from '@fetchkit/ffetch'
+
+const headerPlugin: ClientPlugin = {
+  name: 'header-plugin',
+  preRequest: (ctx) => {
+    ctx.request = new Request(ctx.request, {
+      headers: {
+        ...Object.fromEntries(ctx.request.headers),
+        'x-trace-id': crypto.randomUUID(),
+      },
+    })
+  },
 }
-```
-
-### Usage Examples
-
-```typescript
-import createClient from '@fetchkit/ffetch'
 
-// Basic usage
 const client = createClient({
-  timeout: 5000,
-  retries: 3,
-})
-
-// Pass a custom fetch-compatible implementation (SSR, metaframeworks, polyfills, node-fetch, undici, etc.)
-const client = createClient({
-  timeout: 5000,
-  retries: 3,
-  fetchHandler: fetch, // SvelteKit/Next.js/Nuxt provide their own fetch
+  plugins: [headerPlugin],
 })
-
-// Or use node-fetch/undici in Node.js
-import nodeFetch from 'node-fetch'
-const clientNode = createClient({ fetchHandler: nodeFetch })
-
-// Per-request fetchHandler override (useful for testing)
-const client = createClient({ retries: 0 })
-const mockFetch = () =>
-  Promise.resolve(
-    new Response(JSON.stringify({ test: 'data' }), { status: 200 })
-  )
-await client('https://example.com', { fetchHandler: mockFetch }) // Uses mockFetch
-await client('https://example.com') // Uses global fetch
 ```
 
-## Circuit Breaker Hooks
-
-### onCircuitOpen
+See [plugins.md](./plugins.md) for full lifecycle, ordering, extensions, and advanced patterns.
 
-Called when the circuit transitions to open after consecutive failures. Receives the request that triggered the open event.
+### Removed Legacy Options (Breaking)
 
-Signature: `(req: Request) => void | Promise<void>`
+The following top-level options were removed and now throw a migration error if passed:
 
-### onCircuitClose
+- `dedupe`
+- `dedupeHashFn`
+- `dedupeTTL`
+- `dedupeSweepInterval`
+- `circuit`
 
-Called when the circuit transitions to closed after a successful request. Receives the request that closed the circuit.
+Use plugin modules instead via `plugins: [...]`.
 
-Signature: `(req: Request) => void | Promise<void>`
+### Per-request Overrides
 
-### Example
+Core options can still be overridden per request:
 
-```js
-const client = createClient({
-  circuit: { threshold: 2, reset: 1000 },
-  hooks: {
-    onCircuitOpen: (req) => console.warn('Circuit opened due to:', req.url),
-    onCircuitClose: (req) => console.info('Circuit closed after:', req.url),
-  },
+```typescript
+await client('https://example.com/data', {
+  timeout: 1000,
+  retries: 0,
+  throwOnHttpError: true,
 })
 ```
 
-### Circuit Breaker Behavior
+### Return Type
 
-- Circuit opens after `threshold` consecutive failures. The request that triggers the open is passed to `onCircuitOpen`.
-- Circuit closes after a successful request (after reset period). The successful request is passed to `onCircuitClose`.
+```typescript
+type FFetch = {
+  (input: RequestInfo | URL, init?: RequestInit): Promise<Response>
+  pendingRequests: PendingRequest[]
+  abortAll: () => void
+  // Plugin extensions are composed into this type
+}
+```
 
-### Error Handling
+### Default Values
+
+| Option             | Default Value / Logic                                                                           |
+| ------------------ | ----------------------------------------------------------------------------------------------- |
+| `timeout`          | `5000` ms                                                                                       |
+| `retries`          | `0`                                                                                             |
+| `retryDelay`       | `({ attempt }) => 2 ** attempt * 200 + Math.random() * 100`                                     |
+| `shouldRetry`      | Retries on network errors, HTTP 5xx, or 429. Does not retry 4xx (except 429), abort, or timeout |
+| `throwOnHttpError` | `false`                                                                                         |
+| `hooks`            | `{}`                                                                                            |
+| `plugins`          | `[]`                                                                                            |
+
+### Notes
 
-- Hooks are only called on state transitions, not every request.
-- Request errors and circuit state changes are handled separately.
+- Signal combination (user, timeout, transformRequest) requires `AbortSignal.any`.
+- The first retry attempt uses `attempt = 2`.
+- Plugin order is deterministic: first by `order`, then by registration order.
diff --git a/docs/compatibility.md b/docs/compatibility.md
index 29d3ca9..38120cd 100644
--- a/docs/compatibility.md
+++ b/docs/compatibility.md
@@ -29,7 +29,7 @@ require('abortcontroller-polyfill/dist/polyfill-patch-fetch')
 import 'abort-controller-x/polyfill'
 
 // Now you can use ffetch
-import createClient from '@fetchkit/ffetch'
+import { createClient } from '@fetchkit/ffetch'
 ```
 
 ### Node.js Specific Considerations
@@ -257,7 +257,7 @@ const client = createClient({
 
 ```jsx
 import { useEffect, useState } from 'react'
-import createClient from '@fetchkit/ffetch'
+import { createClient } from '@fetchkit/ffetch'
 
 const client = createClient({ timeout: 5000 })
 
@@ -292,7 +292,7 @@ function DataComponent() {
 
 <script setup>
 import { ref, onMounted, onUnmounted } from 'vue'
-import createClient from '@fetchkit/ffetch'
+import { createClient } from '@fetchkit/ffetch'
 
 const client = createClient({ timeout: 5000 })
 const data = ref(null)
@@ -324,7 +324,7 @@ onUnmounted(() => {
 ```svelte
 <script>
   import { onMount, onDestroy } from 'svelte'
-  import createClient from '@fetchkit/ffetch'
+  import { createClient } from '@fetchkit/ffetch'
 
   const client = createClient({ timeout: 5000 })
   let data = null
diff --git a/docs/deduplication.md b/docs/deduplication.md
index 670e20d..5af3119 100644
--- a/docs/deduplication.md
+++ b/docs/deduplication.md
@@ -1,78 +1,72 @@
 # Request Deduplication
 
-ffetch supports automatic deduplication of in-flight HTTP requests. This feature ensures that identical requests are only sent once, and all callers receive the same response promise.
+Deduplication is provided as an optional plugin.
 
-## How Deduplication Works
+## Import
 
-- When deduplication is enabled, ffetch computes a deduplication key for each request using a hash function.
-- If a request with the same key is already in flight, subsequent callers receive the same promise.
-- Once the request completes, all waiting callers are resolved or rejected together.
-
-## Configuration
-
-Deduplication can be enabled globally or per-request:
-
-```js
-const client = createClient({ dedupe: true })
-client('https://api.example.com/data', { dedupe: true })
+```typescript
+import { createClient } from '@fetchkit/ffetch'
+import {
+  dedupePlugin,
+  dedupeRequestHash,
+} from '@fetchkit/ffetch/plugins/dedupe'
 ```
 
-### Optional Dedupe Map TTL
-
-You can optionally enable stale-entry eviction for the internal dedupe map:
+## Usage
 
-```js
+```typescript
 const client = createClient({
-  dedupe: true,
-  dedupeTTL: 30_000, // Evict dedupe entries older than 30s
-  dedupeSweepInterval: 5_000, // Check every 5s
+  plugins: [dedupePlugin()],
 })
-```
-
-Behavior notes:
-
-- Deduplication works with or without TTL.
-- `dedupeTTL` only controls eviction of dedupe-map keys.
-- TTL eviction does **not** reject an already in-flight request promise.
-- `dedupeSweepInterval` only matters when `dedupeTTL` is a positive number.
 
-### Custom Hash Function
+const p1 = client('https://api.example.com/data')
+const p2 = client('https://api.example.com/data')
+const [r1, r2] = await Promise.all([p1, p2])
+// One network request, shared in-flight promise.
+```
 
-You can provide a custom hash function to control how deduplication keys are generated:
+## Configuration
 
-```js
+```typescript
 const client = createClient({
-  dedupe: true,
-  dedupeHashFn: (params) => `${params.method}|${params.url}|${params.body}`,
+  plugins: [
+    dedupePlugin({
+      hashFn: (params) => `${params.method}|${params.url}|${params.body}`,
+      ttl: 30_000,
+      sweepInterval: 5_000,
+    }),
+  ],
 })
 ```
 
-The default hash function considers method, URL, and body. For advanced use cases, you can include headers or other request properties.
+### Options
 
-## Defaults
+- `hashFn`: Custom key function. Return `undefined` to skip dedupe for a request.
+- `ttl`: Optional map-entry eviction TTL in milliseconds.
+- `sweepInterval`: Sweeper interval in milliseconds when `ttl` is enabled.
+- `order`: Plugin execution order override.
+
+## Behavior Notes
 
-- Deduplication is **off** by default. Enable it via the `dedupe` option.
-- The default hash function is `dedupeRequestHash`, which handles common body types and skips deduplication for streams and FormData.
-- `dedupeTTL` is `undefined` by default (TTL eviction disabled).
-- `dedupeSweepInterval` defaults to `5000` ms.
+- Deduplication is off unless the plugin is installed.
+- TTL eviction only removes in-flight dedupe keys from the map.
+- TTL eviction does not reject already in-flight request promises.
+- Stream/FormData request bodies are skipped by the default hash strategy.
 
-## Limitations
+## Defaults
 
-- **Stream bodies** (`ReadableStream`, `FormData`): Deduplication is skipped for requests with these body types, as they cannot be reliably hashed or replayed.
-- **Non-idempotent requests**: Use deduplication with caution for non-idempotent methods (e.g., POST), as it may suppress multiple intended requests.
-- **Custom hash function**: Ensure your hash function uniquely identifies requests to avoid accidental deduplication.
-- **TTL scope**: `dedupeTTL` does not cache final responses. It only evicts in-flight dedupe keys from the internal map.
+- `hashFn`: `dedupeRequestHash`
+- `ttl`: `undefined` (disabled)
+- `sweepInterval`: `5000`
+- `order`: `10`
 
-## Example
+## Breaking Migration
 
-```js
-const client = createClient({ dedupe: true })
-// These two requests will be deduped and only one fetch will occur
-const p1 = client('https://api.example.com/data')
-const p2 = client('https://api.example.com/data')
-const [r1, r2] = await Promise.all([p1, p2])
-```
+Removed legacy options:
 
-## Summary
+- `dedupe`
+- `dedupeHashFn`
+- `dedupeTTL`
+- `dedupeSweepInterval`
 
-Deduplication in ffetch helps reduce redundant network traffic and ensures consistent responses for identical requests. Configure it as needed, and be aware of its limitations for certain body types and request methods.
+Use `plugins: [dedupePlugin(...)]` instead.
diff --git a/docs/examples.md b/docs/examples.md
index e84c186..6540045 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -9,10 +9,11 @@ Real-world examples and patterns for using `@fetchkit/ffetch` in different scena
 You can inspect the circuit breaker state at runtime using `client.circuitOpen` to avoid making requests when the circuit is open:
 
 ```typescript
-import createClient from '@fetchkit/ffetch'
+import { createClient } from '@fetchkit/ffetch'
+import { circuitPlugin } from '@fetchkit/ffetch/plugins/circuit'
 
 const client = createClient({
-  circuit: { threshold: 5, reset: 30000 },
+  plugins: [circuitPlugin({ threshold: 5, reset: 30000 })],
 })
 
 if (client.circuitOpen) {
@@ -28,7 +29,7 @@ if (client.circuitOpen) {
 ### Simple HTTP Client
 
 ```typescript
-import createClient from '@fetchkit/ffetch'
+import { createClient } from '@fetchkit/ffetch'
 
 const api = createClient({
   timeout: 10000,
@@ -49,7 +50,7 @@ const newUser = await api('https://api.example.com/users', {
 ### REST API Client
 
 ```typescript
-import createClient, { type FFetch } from '@fetchkit/ffetch'
+import { createClient, type FFetch } from '@fetchkit/ffetch'
 
 class ApiClient {
   private client: FFetch
@@ -117,7 +118,7 @@ const newUser = await api.post<User>('/users', { name: 'John' })
 ### Using ffetch with a Custom Fetch (e.g., node-fetch)
 
 ```typescript
-import createClient from '@fetchkit/ffetch'
+import { createClient } from '@fetchkit/ffetch'
 import fetch from 'node-fetch'
 
 const client = createClient({ fetchHandler: fetch })
@@ -130,7 +131,7 @@ const data = await response.json()
 You can provide a mock fetch handler at the client level or override it per-request:
 
 ```typescript
-import createClient from '@fetchkit/ffetch'
+import { createClient } from '@fetchkit/ffetch'
 
 function mockFetch(url, options) {
   return Promise.resolve(
@@ -169,7 +170,7 @@ const postsResponse = await client2('/api/posts', { fetchHandler: mockPosts })
 ### Microservices Client
 
 ```typescript
-import createClient, { type FFetch } from '@fetchkit/ffetch'
+import { createClient, type FFetch } from '@fetchkit/ffetch'
 
 interface ServiceConfig {
   baseUrl: string
@@ -193,7 +194,14 @@ class MicroserviceClient {
       const client = createClient({
         timeout: config.timeout || 5000,
         retries: config.retries || 2,
-        circuit: config.circuitBreaker,
+        plugins: config.circuitBreaker
+          ? [
+              circuitPlugin({
+                threshold: config.circuitBreaker.threshold,
+                reset: config.circuitBreaker.reset,
+              }),
+            ]
+          : [],
         hooks: {
           transformRequest: async (req) => {
             // Properly construct full URL
@@ -275,7 +283,7 @@ const client = new MicroserviceClient({
 ### GraphQL Client
 
 ```typescript
-import createClient, { type FFetch } from '@fetchkit/ffetch'
+import { createClient, type FFetch } from '@fetchkit/ffetch'
 
 class GraphQLClient {
   private client: FFetch
@@ -365,7 +373,7 @@ const user = await gql.query(
 ### File Upload Client
 
 ```typescript
-import createClient, { type FFetch } from '@fetchkit/ffetch'
+import { createClient, type FFetch } from '@fetchkit/ffetch'
 
 class FileUploadClient {
   private client: FFetch
@@ -462,7 +470,7 @@ const results = await uploader.uploadMultiple(files, '/api/upload')
 For very large uploads, streaming operations, or long-running requests where you don't want any timeout:
 
 ```typescript
-import createClient from '@fetchkit/ffetch'
+import { createClient } from '@fetchkit/ffetch'
 
 // Client with no timeout - useful for streaming or very large uploads
 const streamingClient = createClient({
@@ -505,7 +513,7 @@ async function longRequest() {
 ### Real-time Data Polling
 
 ```typescript
-import createClient, { AbortError, type FFetch } from '@fetchkit/ffetch'
+import { createClient, AbortError, type FFetch } from '@fetchkit/ffetch'
 
 class DataPoller {
   private client: FFetch
@@ -580,12 +588,16 @@ window.addEventListener('beforeunload', () => poller.stopPolling())
 Use this when you want to dedupe concurrent identical requests and optionally evict stale in-flight dedupe keys:
 
 ```typescript
-import createClient from '@fetchkit/ffetch'
+import { createClient } from '@fetchkit/ffetch'
+import { dedupePlugin } from '@fetchkit/ffetch/plugins/dedupe'
 
 const client = createClient({
-  dedupe: true,
-  dedupeTTL: 30_000,
-  dedupeSweepInterval: 5_000,
+  plugins: [
+    dedupePlugin({
+      ttl: 30_000,
+      sweepInterval: 5_000,
+    }),
+  ],
 })
 
 const p1 = client('https://api.example.com/profile')
@@ -595,10 +607,10 @@ const p2 = client('https://api.example.com/profile')
 const [r1, r2] = await Promise.all([p1, p2])
 ```
 
-> Note: `dedupeTTL` is not response caching TTL. It only evicts entries in the internal dedupe map.
+> Note: dedupe plugin `ttl` is not response caching TTL. It only evicts entries in the internal dedupe map.
 
 ```typescript
-import createClient, { type FFetch } from '@fetchkit/ffetch'
+import { createClient, type FFetch } from '@fetchkit/ffetch'
 
 interface CacheEntry<T> {
   data: T
@@ -707,6 +719,9 @@ const result = await cachedClient.post('/api/search', { query: 'test' }, 30000)
 ### Graceful Degradation
 
 ```typescript
+import { createClient, type FFetch } from '@fetchkit/ffetch'
+import { circuitPlugin } from '@fetchkit/ffetch/plugins/circuit'
+
 class ResilientApiClient {
   private client: FFetch
   private fallbackData: Record<string, any> = {}
@@ -715,7 +730,7 @@ class ResilientApiClient {
     this.client = createClient({
       timeout: 5000,
       retries: 3,
-      circuit: { threshold: 5, reset: 30000 },
+      plugins: [circuitPlugin({ threshold: 5, reset: 30000 })],
     })
   }
 
diff --git a/docs/hooks.md b/docs/hooks.md
index ed082a9..edca6cb 100644
--- a/docs/hooks.md
+++ b/docs/hooks.md
@@ -12,7 +12,6 @@ Hooks allow you to observe, log, or modify the request/response lifecycle. All h
 - `onRetry(req, attempt, err, res)`: Called before each retry attempt
 - `onTimeout(req)`: Called when a request times out
 - `onAbort(req)`: Called when a request is aborted by the user
-- `onCircuitOpen(req)`: Called when the circuit breaker is open and a request is blocked
 - `onComplete(req, res, err)`: Called after every request, whether it succeeded or failed
 
 ### Basic Hooks Example
@@ -26,7 +25,6 @@ const client = createClient({
     onRetry: async (req, attempt, err) => console.log('Retrying', attempt),
     onTimeout: async (req) => console.warn('Timeout:', req.url),
     onAbort: async (req) => console.warn('Aborted:', req.url),
-    onCircuitOpen: async (req) => console.warn('Circuit open:', req.url),
     onComplete: async (req, res, err) => console.log('Done:', req.url),
   },
 })
@@ -274,7 +272,7 @@ const client = createClient({
 })
 ```
 
-## Circuit Breaker Hooks
+## Circuit Breaker Plugin Callbacks
 
 ### onCircuitOpen
 
@@ -291,12 +289,18 @@ Signature: `(req: Request) => void | Promise<void>`
 ### Example
 
 ```js
+import { createClient } from '@fetchkit/ffetch'
+import { circuitPlugin } from '@fetchkit/ffetch/plugins/circuit'
+
 const client = createClient({
-  circuit: { threshold: 2, reset: 1000 },
-  hooks: {
-    onCircuitOpen: (req) => console.warn('Circuit opened due to:', req.url),
-    onCircuitClose: (req) => console.info('Circuit closed after:', req.url),
-  },
+  plugins: [
+    circuitPlugin({
+      threshold: 2,
+      reset: 1000,
+      onCircuitOpen: (req) => console.warn('Circuit opened due to:', req.url),
+      onCircuitClose: (req) => console.info('Circuit closed after:', req.url),
+    }),
+  ],
 })
 ```
 
@@ -317,8 +321,8 @@ If an error occurs or retry is needed:
 2. `onRetry` - Called before retry attempts
 3. `onTimeout` - Called on timeout errors
 4. `onAbort` - Called on abort errors
-5. `onCircuitOpen` - Called when circuit breaker transitions to open
-6. `onCircuitClose` - Called when circuit breaker transitions to closed
+5. Plugin `onCircuitOpen` callback - Called when circuit breaker transitions to open
+6. Plugin `onCircuitClose` callback - Called when circuit breaker transitions to closed
 7. `onComplete` - Always called last
 
 ## Per-Request Hooks
diff --git a/docs/index.md b/docs/index.md
index 870531a..93e4c2b 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -13,11 +13,19 @@
   - Configuration parameters and defaults
   - TypeScript interfaces and types
 
+### **Plugin Architecture**
+
+- **[plugins.md](./plugins.md)** - Plugin lifecycle, ordering, custom plugin authoring
+  - Built-in feature plugins (`dedupe`, `circuit`)
+  - Writing and registering custom plugins
+  - Public plugin types and extension patterns
+
 ### **Getting Started**
 
 - **[migration.md](./migration.md)** - Migration guide from native fetch to ffetch
   - Drop-in replacement patterns
   - Error handling differences
+  - v4 -> v5 plugin migration (`dedupe`/`circuit` flags -> plugins)
   - New capabilities and features
   - TypeScript migration tips
 
@@ -58,8 +66,9 @@
 1. **Start with the [README](../README.md)** for installation and basic usage
 2. **Check [compatibility.md](./compatibility.md)** to ensure your environment is supported
 3. **Read [api.md](./api.md)** for complete configuration options
-4. **Explore [examples.md](./examples.md)** for patterns that match your use case
-5. **Dive into [advanced.md](./advanced.md)** and [hooks.md](./hooks.md)\*\* for powerful features
+4. **Read [plugins.md](./plugins.md)** to understand plugin architecture and custom extensions
+5. **Explore [examples.md](./examples.md)** for patterns that match your use case
+6. **Dive into [advanced.md](./advanced.md)** and [hooks.md](./hooks.md)\*\* for powerful features
 
 ## **Finding What You Need**
 
@@ -71,6 +80,8 @@
 | Error handling                                   | [errorhandling.md](./errorhandling.md)                       |
 | Deduplicate requests (with optional TTL cleanup) | [deduplication.md](./deduplication.md)                       |
 | Migrate from native fetch                        | [migration.md](./migration.md)                               |
+| Understand plugin architecture                   | [plugins.md](./plugins.md)                                   |
+| Write a custom plugin                            | [plugins.md](./plugins.md#writing-a-custom-plugin)           |
 | See all configuration options                    | [api.md](./api.md)                                           |
 | Handle errors gracefully                         | [advanced.md](./advanced.md#custom-error-handling)           |
 | Add authentication to requests                   | [hooks.md](./hooks.md#authentication)                        |
@@ -89,7 +100,7 @@
 
 - **Timeouts**: Per-request or global timeout configuration
 - **Retries**: Exponential backoff with jitter and custom retry logic
-- **Circuit Breaker**: Automatic failure protection and recovery
+- **Plugin-based optional features**: Circuit breaker, dedupe, and third-party plugins
 - **Hooks**: Lifecycle events for logging, auth, and transformation
 - **Pending Requests**: Real-time monitoring of active requests
 - **Custom fetch wrapping**: Pluggable fetch implementation for SSR, node-fetch, undici, and framework-provided fetch
@@ -113,7 +124,7 @@
 ### **Basic HTTP Client**
 
 ```typescript
-import createClient from '@fetchkit/ffetch'
+import { createClient } from '@fetchkit/ffetch'
 
 const api = createClient({
   timeout: 5000,
diff --git a/docs/migration.md b/docs/migration.md
index dba71c6..fa98d3d 100644
--- a/docs/migration.md
+++ b/docs/migration.md
@@ -1,433 +1,157 @@
-# Migration Guide: From Native Fetch to ffetch
+# Migration Guide
 
-This guide helps you migrate from native `fetch()` to `ffetch` while understanding the differences and new capabilities.
+This guide covers migration to ffetch v5.0.0, with focus on the breaking move from config-based optional features to plugins.
 
-## Quick Start Migration
+## Who Needs This Guide
 
-### Basic Replacement
+Use this guide if your v4 code uses any of these options:
 
-```typescript
-// Before: Native fetch
-const response = await fetch('https://api.example.com/data')
-const data = await response.json()
-
-// After: ffetch
-import createClient from '@fetchkit/ffetch'
-const client = createClient()
-const response = await client('https://api.example.com/data')
-const data = await response.json()
-```
-
-### With Options
-
-```typescript
-// Before: Native fetch with options
-const response = await fetch('https://api.example.com/data', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ name: 'John' }),
-  signal: abortController.signal,
-})
-
-// After: ffetch (same options + new ones)
-const response = await client('https://api.example.com/data', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ name: 'John' }),
-  signal: abortController.signal,
-  // New ffetch-specific options
-  timeout: 5000,
-  retries: 3,
-})
-```
+- `dedupe`
+- `dedupeHashFn`
+- `dedupeTTL`
+- `dedupeSweepInterval`
+- `circuit`
 
-## Key Compatibility Points
+## v5.0.0 Breaking Changes
 
-### ✅ **Fully Compatible & Pluggable**
+1. Root import is named-only.
+2. Optional features moved to plugin modules.
+3. Legacy top-level feature flags are removed.
 
-ffetch can now be used as a drop-in wrapper for custom fetch implementations. This makes migration easier for SSR/metaframeworks (SvelteKit, Next.js, Nuxt, etc.) and for environments where you need to provide your own fetch (e.g., node-fetch, undici, framework-provided fetch).
+## 1) Import Changes
 
-Simply pass your custom fetch implementation using the `fetchHandler` option:
+### Before (v4)
 
 ```typescript
 import createClient from '@fetchkit/ffetch'
-import fetch from 'node-fetch'
-
-const client = createClient({ fetchHandler: fetch })
-```
-
-These work exactly the same as native fetch:
-
-```typescript
-// HTTP status handling - identical to native fetch
-const response = await client('https://api.example.com/data')
-if (!response.ok) {
-  console.log('HTTP error:', response.status) // Same as native fetch
-}
-
-// Request/Response objects - same Web API objects
-const request = new Request('https://api.example.com')
-const response = await client(request)
-
-// AbortSignal - same Web API
-const controller = new AbortController()
-const response = await client('/api/data', { signal: controller.signal })
-```
-
-### 🔄 **Enhanced but Compatible**
-
-These work the same but with additional features:
-
-```typescript
-// RequestInit extended with new options
-const response = await client('/api/data', {
-  // All native fetch options work
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-
-  // Plus new ffetch options
-  timeout: 10000,
-  retries: 2,
-  retryDelay: 1000,
-})
 ```
 
-## Error Handling Migration
-
-### Native Fetch Error Patterns
+### After (v5)
 
 ```typescript
-// Native fetch error handling
-try {
-  const response = await fetch('https://api.example.com/data')
-
-  if (!response.ok) {
-    throw new Error(`HTTP ${response.status}: ${response.statusText}`)
-  }
-
-  const data = await response.json()
-} catch (err) {
-  if (err instanceof TypeError) {
-    console.log('Network error:', err.message)
-  } else if (err instanceof DOMException && err.name === 'AbortError') {
-    console.log('Request was aborted')
-  } else {
-    console.log('Other error:', err)
-  }
-}
+import { createClient } from '@fetchkit/ffetch'
 ```
 
-### ffetch Enhanced Error Handling
+## 2) Feature Flag Migration Map
 
-```typescript
-import createClient, {
-  NetworkError,
-  AbortError,
-  TimeoutError,
-  RetryLimitError,
-} from '@fetchkit/ffetch'
-
-const client = createClient({ timeout: 5000, retries: 2 })
-
-try {
-  const response = await client('https://api.example.com/data')
-
-  // HTTP error handling - same as native fetch
-  if (!response.ok) {
-    throw new Error(`HTTP ${response.status}: ${response.statusText}`)
-  }
-
-  const data = await response.json()
-} catch (err) {
-  // Enhanced error types with original errors preserved in .cause
-  if (err instanceof NetworkError) {
-    console.log('Network error:', err.message)
-    console.log('Original error:', err.cause) // Access native TypeError
-  } else if (err instanceof AbortError) {
-    console.log('Request was aborted')
-    console.log('Original error:', err.cause) // Access native DOMException
-  } else if (err instanceof TimeoutError) {
-    console.log('Request timed out') // New: automatic timeout handling
-  } else if (err instanceof RetryLimitError) {
-    console.log('Failed after retries') // New: retry exhaustion
-  }
-}
-```
+| v4 Option                       | v5 Replacement                                   |
+| ------------------------------- | ------------------------------------------------ |
+| `dedupe: true`                  | `plugins: [dedupePlugin()]`                      |
+| `dedupeHashFn`                  | `dedupePlugin({ hashFn })`                       |
+| `dedupeTTL`                     | `dedupePlugin({ ttl })`                          |
+| `dedupeSweepInterval`           | `dedupePlugin({ sweepInterval })`                |
+| `circuit: { threshold, reset }` | `plugins: [circuitPlugin({ threshold, reset })]` |
 
-### Accessing Original Native Errors
+## 3) Dedupe Migration
 
-```typescript
-// If you need the exact native error for compatibility
-try {
-  await client('/api/data')
-} catch (err) {
-  if (err instanceof NetworkError) {
-    const originalTypeError = err.cause // This is the native TypeError
-    // Handle as you would with native fetch
-  }
-
-  if (err instanceof AbortError) {
-    const originalDOMException = err.cause // This is the native DOMException
-    // originalDOMException.name === 'AbortError'
-  }
-}
-```
-
-## New Capabilities
-
-### Automatic Retries
+### Before (v4)
 
 ```typescript
-// Native fetch - manual retry logic needed
-async function fetchWithRetry(url, options, retries = 3) {
-  for (let i = 0; i <= retries; i++) {
-    try {
-      const response = await fetch(url, options)
-      if (response.ok || i === retries) return response
-    } catch (err) {
-      if (i === retries) throw err
-    }
-    await new Promise((resolve) => setTimeout(resolve, 1000 * Math.pow(2, i)))
-  }
-}
+import createClient from '@fetchkit/ffetch'
 
-// ffetch - built-in retries
 const client = createClient({
-  retries: 3,
-  retryDelay: ({ attempt }) => 1000 * Math.pow(2, attempt),
+  dedupe: true,
+  dedupeHashFn: (params) => `${params.method}|${params.url}|${params.body}`,
+  dedupeTTL: 30_000,
+  dedupeSweepInterval: 5_000,
 })
-const response = await client('/api/data') // Automatically retries
 ```
 
-### Automatic Timeouts
+### After (v5)
 
 ```typescript
-// Native fetch - manual timeout needed
-function fetchWithTimeout(url, options, timeout = 5000) {
-  const controller = new AbortController()
-  const timeoutId = setTimeout(() => controller.abort(), timeout)
-
-  return fetch(url, {
-    ...options,
-    signal: controller.signal,
-  }).finally(() => clearTimeout(timeoutId))
-}
+import { createClient } from '@fetchkit/ffetch'
+import { dedupePlugin } from '@fetchkit/ffetch/plugins/dedupe'
 
-// ffetch - built-in timeout
-const client = createClient({ timeout: 5000 })
-const response = await client('/api/data') // Automatically times out
-```
-
-### Circuit Breaker
-
-```typescript
-// Native fetch - no built-in circuit breaker
-// You'd need to implement this manually
-
-// ffetch - built-in circuit breaker
 const client = createClient({
-  circuit: {
-    threshold: 5, // Open after 5 failures
-    reset: 30000, // Try again after 30 seconds
-  },
+  plugins: [
+    dedupePlugin({
+      hashFn: (params) => `${params.method}|${params.url}|${params.body}`,
+      ttl: 30_000,
+      sweepInterval: 5_000,
+    }),
+  ],
 })
-const response = await client('/api/data') // Automatically circuit breaks
 ```
 
-## Migration Strategy
+## 4) Circuit Breaker Migration
 
-### 1. **Drop-in Replacement**
-
-Start by replacing `fetch` calls with minimal changes:
+### Before (v4)
 
 ```typescript
-// Step 1: Basic replacement
-- const response = await fetch(url, options)
-+ const client = createClient()
-+ const response = await client(url, options)
-```
-
-### 2. **Add Basic Enhancements**
+import createClient from '@fetchkit/ffetch'
 
-```typescript
-// Step 2: Add timeout and retries
 const client = createClient({
-  timeout: 10000,
-  retries: 2,
+  retries: 0,
+  circuit: { threshold: 5, reset: 30_000 },
+  hooks: {
+    onCircuitOpen: (req) => console.warn('Circuit opened:', req.url),
+    onCircuitClose: (req) => console.info('Circuit closed:', req.url),
+  },
 })
 ```
 
-### 3. **Enhance Error Handling**
+### After (v5)
 
 ```typescript
-// Step 3: Use enhanced error types
-import { NetworkError, TimeoutError, RetryLimitError } from '@fetchkit/ffetch'
-
-try {
-  const response = await client('/api/data')
-} catch (err) {
-  if (err instanceof NetworkError) {
-    // Handle network issues
-  } else if (err instanceof TimeoutError) {
-    // Handle timeouts
-  }
-  // Original error always available in err.cause
-}
-```
-
-### 4. **Add Advanced Features**
+import { createClient } from '@fetchkit/ffetch'
+import { circuitPlugin } from '@fetchkit/ffetch/plugins/circuit'
 
-```typescript
-// Step 4: Add hooks, circuit breaker, etc.
 const client = createClient({
-  timeout: 10000,
-  retries: 3,
-  circuit: { threshold: 5, reset: 30000 },
-  hooks: {
-    before: (req) => console.log('Making request to:', req.url),
-    onError: (req, err) => console.log('Request failed:', err.message),
-  },
+  retries: 0,
+  plugins: [
+    circuitPlugin({
+      threshold: 5,
+      reset: 30_000,
+      onCircuitOpen: (req) => console.warn('Circuit opened:', req.url),
+      onCircuitClose: (req) => console.info('Circuit closed:', req.url),
+    }),
+  ],
 })
 ```
 
-## Common Gotchas
+## 5) Circuit State Access
 
-### 1. **Signal Combination**
+When `circuitPlugin` is installed, `client.circuitOpen` is available as a plugin extension.
 
 ```typescript
-// Native fetch - one signal only
-const controller = new AbortController()
-const response = await fetch(url, { signal: controller.signal })
-
-// ffetch - combines multiple signals automatically using AbortSignal.any
-// Requires AbortSignal.any (native or polyfill)
-const controller = new AbortController()
-const response = await client(url, {
-  signal: controller.signal, // User signal
-  timeout: 5000, // Creates timeout signal
-  // Both signals are automatically combined
-})
-// If AbortSignal.any is not available, you must install a polyfill before using ffetch
-```
-
-### 2. **Error Instance Checks**
-
-```typescript
-// If you have existing error handling that checks for specific types
-try {
-  await client('/api/data')
-} catch (err) {
-  // OLD: This won't work anymore
-  if (err instanceof TypeError) {
-    /* ... */
-  }
-
-  // NEW: Check ffetch error types first, then check .cause
-  if (err instanceof NetworkError && err.cause instanceof TypeError) {
-    // Handle network error (original TypeError in err.cause)
-  }
+if (client.circuitOpen) {
+  console.warn('Circuit is open')
 }
 ```
 
-### 3. **Pending Requests**
+TypeScript tip: keep plugin lists as tuples for best inference.
 
 ```typescript
-// Native fetch - no built-in way to track pending requests
-// You'd need to manage this manually
-
-// ffetch - built-in pending request tracking
-const client = createClient()
-client('/api/data')
-client('/api/other')
-
-console.log('Pending requests:', client.pendingRequests.length) // 2
-
-// Access individual pending requests
-client.pendingRequests[0].controller.abort() // Abort first request
-
-// Abort all pending requests (new in v3)
-client.abortAll() // Instantly aborts all active requests
+const plugins = [circuitPlugin({ threshold: 5, reset: 30_000 })] as const
+const client = createClient({ plugins })
 ```
 
-## TypeScript Migration
+## 6) Runtime Guard for Legacy Options
 
-### Type Definitions
+v5 throws a clear runtime error if removed options are still present in client options or per-request init.
 
-```typescript
-// Native fetch types
-function myFetch(
-  input: RequestInfo | URL,
-  init?: RequestInit
-): Promise<Response>
-
-// ffetch types - extends RequestInit
-import { FFetch, FFetchRequestInit } from '@fetchkit/ffetch'
-
-function myFFetch(
-  input: RequestInfo | URL,
-  init?: FFetchRequestInit
-): Promise<Response>
-
-// FFetchRequestInit extends RequestInit with additional options
-const options: FFetchRequestInit = {
-  method: 'POST', // Standard RequestInit
-  headers: {}, // Standard RequestInit
-  timeout: 5000, // ffetch extension
-  retries: 3, // ffetch extension
-}
+## 7) Quick Upgrade Checklist
 
-// PendingRequest type changed in v3:
-// Old: { promise, request, signal }
-// New: { promise, request, controller }
-```
+1. Replace default root import with named root import.
+2. Add plugin imports from:
+   - `@fetchkit/ffetch/plugins/dedupe`
+   - `@fetchkit/ffetch/plugins/circuit`
+3. Move dedupe and circuit config into `plugins: [...]`.
+4. Move circuit callbacks from `hooks` into `circuitPlugin(...)` options.
+5. Run tests and verify no legacy options remain.
 
-## Performance Considerations
+## Native Fetch Users
 
-### Bundle Size
+If migrating directly from native `fetch`, start with:
 
 ```typescript
-// Native fetch - 0 bytes (built into platform)
-// ffetch - ~3KB gzipped additional size
-
-// Tree-shaking: Only import what you need
-import createClient from '@fetchkit/ffetch' // Full library
-import { NetworkError, TimeoutError } from '@fetchkit/ffetch' // Just error types
-```
-
-### Memory Usage
+import { createClient } from '@fetchkit/ffetch'
 
-```typescript
-// ffetch keeps track of pending requests
-const client = createClient()
-
-// Each request adds to pendingRequests array until completion
-const response = await client('/api/data') // Automatically removed when done
-
-// For long-running apps, this is handled automatically
-// No memory leaks as requests are cleaned up on completion
+const client = createClient({
+  timeout: 5000,
+  retries: 2,
+})
 ```
 
-## Best Practices for Migration
-
-1. **Start Simple**: Begin with basic timeout and retry configuration
-2. **Gradual Enhancement**: Add advanced features incrementally
-3. **Test Error Handling**: Verify your error handling works with new error types
-4. **Monitor Performance**: Check that enhanced features don't impact performance
-5. **Leverage TypeScript**: Use type definitions for better development experience
-
-## Rollback Strategy
-
-If you need to rollback to native fetch:
-
-```typescript
-// Create a compatibility wrapper
-function createFetchClient() {
-  return fetch.bind(window) // or global fetch
-}
-
-// Replace ffetch usage with minimal changes
-- const client = createClient()
-+ const client = createFetchClient()
-
-// Most code will work unchanged due to ffetch's fetch compatibility
-```
+Then add plugins only when needed.
diff --git a/docs/plugins.md b/docs/plugins.md
new file mode 100644
index 0000000..d18d790
--- /dev/null
+++ b/docs/plugins.md
@@ -0,0 +1,148 @@
+# Plugin Architecture
+
+From version 5 ffetch uses a plugin pipeline for optional behavior such as deduplication and circuit breaking.
+
+## Why Plugins
+
+- Keep the core client small.
+- Make optional features tree-shakeable.
+- Support first-party and third-party extensions.
+
+## Lifecycle Overview
+
+Plugins can hook into request execution at multiple phases:
+
+1. `setup` (once, at client creation): register client extensions.
+2. `preRequest` (per request, before dispatch): validate or prepare request context.
+3. `wrapDispatch` (per request): wrap the network dispatch function.
+4. `onSuccess` (per request): run after successful completion.
+5. `onError` (per request): run after failure.
+6. `onFinally` (per request): always run when request settles.
+
+## Plugin Order
+
+Execution order is deterministic:
+
+- Plugins are sorted by `order` (ascending).
+- For equal `order`, registration order is preserved.
+
+## Built-in Feature Plugins
+
+```typescript
+import { createClient } from '@fetchkit/ffetch'
+import { dedupePlugin } from '@fetchkit/ffetch/plugins/dedupe'
+import { circuitPlugin } from '@fetchkit/ffetch/plugins/circuit'
+
+const client = createClient({
+  plugins: [
+    dedupePlugin({ ttl: 30_000, sweepInterval: 5_000 }),
+    circuitPlugin({ threshold: 5, reset: 30_000 }),
+  ],
+})
+```
+
+## Writing a Custom Plugin
+
+Use the public `ClientPlugin` type.
+
+```typescript
+import { createClient, type ClientPlugin } from '@fetchkit/ffetch'
+
+type TimingExtension = {
+  lastDurationMs: number
+}
+
+function timingPlugin(): ClientPlugin<TimingExtension> {
+  let lastDurationMs = 0
+
+  return {
+    name: 'timing',
+    order: 100,
+    setup: ({ defineExtension }) => {
+      defineExtension('lastDurationMs', {
+        get: () => lastDurationMs,
+      })
+    },
+    preRequest: (ctx) => {
+      ctx.state.start = Date.now()
+    },
+    onFinally: (ctx) => {
+      const start =
+        typeof ctx.state.start === 'number' ? ctx.state.start : Date.now()
+      lastDurationMs = Date.now() - start
+    },
+  }
+}
+
+const client = createClient({
+  plugins: [timingPlugin()] as const,
+})
+
+await client('https://example.com/data')
+console.log(client.lastDurationMs)
+```
+
+## Plugin Context and Types
+
+For advanced plugins, import public context types:
+
+```typescript
+import type {
+  ClientPlugin,
+  PluginRequestContext,
+  PluginDispatch,
+  PluginSetupContext,
+} from '@fetchkit/ffetch'
+```
+
+What you can access in request context:
+
+- `ctx.request`: current `Request` object.
+- `ctx.init`: request init/options.
+- `ctx.state`: per-request mutable plugin state.
+- `ctx.metadata`: signal and retry metadata.
+
+## Wrapping Dispatch
+
+Use `wrapDispatch` when you need around-advice behavior (before/after dispatch in one place):
+
+```typescript
+import type { ClientPlugin } from '@fetchkit/ffetch'
+
+const tracingPlugin: ClientPlugin = {
+  name: 'tracing',
+  wrapDispatch: (next) => async (ctx) => {
+    console.log('start', ctx.request.url)
+    try {
+      const response = await next(ctx)
+      console.log('end', response.status)
+      return response
+    } catch (error) {
+      console.log('error', error)
+      throw error
+    }
+  },
+}
+```
+
+## Registering and Using Custom Plugins
+
+```typescript
+import { createClient } from '@fetchkit/ffetch'
+
+const client = createClient({
+  timeout: 10_000,
+  retries: 2,
+  plugins: [
+    // custom plugin instances
+  ],
+})
+```
+
+## Best Practices
+
+- Keep plugins side-effect free outside controlled state.
+- Prefer per-request data in `ctx.state` instead of global mutable variables.
+- Use `order` only when needed; document ordering assumptions.
+- Avoid throwing from `onFinally` unless intentional.
+- Use `as const` plugin tuples for best TypeScript extension inference.
diff --git a/package.json b/package.json
index fc46be5..768304a 100644
--- a/package.json
+++ b/package.json
@@ -26,6 +26,16 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
+    },
+    "./plugins/dedupe": {
+      "types": "./dist/plugins/dedupe.d.ts",
+      "import": "./dist/plugins/dedupe.js",
+      "require": "./dist/plugins/dedupe.cjs"
+    },
+    "./plugins/circuit": {
+      "types": "./dist/plugins/circuit.d.ts",
+      "import": "./dist/plugins/circuit.js",
+      "require": "./dist/plugins/circuit.cjs"
     }
   },
   "files": [
diff --git a/src/circuit.ts b/src/circuit.ts
deleted file mode 100644
index 729fc86..0000000
--- a/src/circuit.ts
+++ /dev/null
@@ -1,94 +0,0 @@
-import { CircuitOpenError, RetryLimitError } from './error.js'
-
-export class CircuitBreaker {
-  private failures = 0
-  private nextAttempt = 0
-  private isOpen = false
-
-  // Returns true if the circuit breaker is currently open (blocking requests).
-  get open(): boolean {
-    return this.isOpen
-  }
-  private hooks?: {
-    onCircuitOpen?: (req: Request) => void | Promise<void>
-    onCircuitClose?: (req: Request) => void | Promise<void>
-  }
-  private lastSuccessRequest?: Request
-  private lastOpenRequest?: Request
-
-  constructor(
-    private threshold: number,
-    private resetTimeout: number
-  ) {}
-
-  // Call this after each request to record the result and update circuit state.
-  // Returns true if the result was counted as a failure.
-  recordResult(response?: Response, error?: unknown, req?: Request): boolean {
-    // Count thrown errors (network, abort, timeout) as failures
-    if (error && !(error instanceof RetryLimitError)) {
-      this.setLastOpenRequest(req!)
-      this.onFailure()
-      return true
-    }
-    // Count HTTP 5xx and 429 responses as failures
-    if (response && (response.status >= 500 || response.status === 429)) {
-      this.setLastOpenRequest(req!)
-      this.onFailure()
-      return true
-    }
-    // Otherwise, count as success
-    if (req) this.setLastSuccessRequest(req)
-    this.onSuccess()
-    return false
-  }
-
-  setHooks(hooks: {
-    onCircuitOpen?: (req: Request) => void | Promise<void>
-    onCircuitClose?: (req: Request) => void | Promise<void>
-  }) {
-    this.hooks = hooks
-  }
-  setLastOpenRequest(req: Request) {
-    this.lastOpenRequest = req
-  }
-
-  setLastSuccessRequest(req: Request) {
-    this.lastSuccessRequest = req
-  }
-
-  async invoke<T>(fn: () => Promise<T>): Promise<T> {
-    if (Date.now() < this.nextAttempt)
-      throw new CircuitOpenError('Circuit is open')
-    try {
-      const res = await fn()
-      this.onSuccess()
-      return res
-    } catch (err) {
-      this.onFailure()
-      throw err
-    }
-  }
-
-  private onSuccess() {
-    const wasOpen = this.isOpen
-    this.failures = 0
-    if (wasOpen) {
-      this.isOpen = false
-      if (this.hooks?.onCircuitClose && this.lastSuccessRequest) {
-        this.hooks.onCircuitClose(this.lastSuccessRequest)
-      }
-    }
-    this.lastSuccessRequest = undefined
-  }
-
-  private onFailure() {
-    this.failures++
-    if (this.failures >= this.threshold) {
-      this.nextAttempt = Date.now() + this.resetTimeout
-      this.isOpen = true
-      if (this.hooks?.onCircuitOpen && this.lastOpenRequest) {
-        this.hooks.onCircuitOpen(this.lastOpenRequest)
-      }
-    }
-  }
-}
diff --git a/src/client.ts b/src/client.ts
index 11e708c..d764134 100644
--- a/src/client.ts
+++ b/src/client.ts
@@ -4,82 +4,74 @@ import type {
   FFetchRequestInit,
   PendingRequest,
 } from './types.js'
-import { dedupeRequestHash } from './dedupeRequestHash.js'
 import { retry, defaultDelay } from './retry.js'
 import { shouldRetry as defaultShouldRetry } from './should-retry.js'
-import { CircuitBreaker } from './circuit.js'
+import {
+  type PluginDispatch,
+  type PluginRequestContext,
+  type PluginExtensions,
+  type ClientPlugin,
+  type PluginExtensionBase,
+} from './plugins.js'
 import {
   TimeoutError,
-  CircuitOpenError,
   AbortError,
   RetryLimitError,
   NetworkError,
 } from './error.js'
 
-export function createClient(opts: FFetchOptions = {}): FFetch {
-  // Sweeper timer for dedupe TTL
-  let dedupeSweeper: ReturnType<typeof setInterval> | undefined
-
-  function startDedupeSweeper() {
-    if (dedupeSweeper || !dedupeTTL) return
-    dedupeSweeper = setInterval(() => {
-      const now = Date.now()
-      for (const [key, entry] of dedupeMap.entries()) {
-        if (now - entry.createdAt > dedupeTTL) {
-          dedupeMap.delete(key)
-        }
-      }
-      if (dedupeMap.size === 0 && dedupeSweeper) {
-        clearInterval(dedupeSweeper)
-        dedupeSweeper = undefined
-      }
-    }, dedupeSweepInterval)
-  }
-
-  function stopDedupeSweeperIfIdle() {
-    if (dedupeMap.size === 0 && dedupeSweeper) {
-      clearInterval(dedupeSweeper)
-      dedupeSweeper = undefined
-    }
-  }
-
-  const dedupeMap = new Map<
-    string,
-    {
-      promise: Promise<Response>
-      resolve: (value: Response | PromiseLike<Response>) => void
-      reject: (reason?: unknown) => void
-      createdAt: number
-    }
-  >()
+export function createClient<
+  TPlugins extends
+    readonly ClientPlugin<PluginExtensionBase>[] = readonly ClientPlugin<PluginExtensionBase>[],
+>(
+  opts: FFetchOptions<TPlugins> = {} as FFetchOptions<TPlugins>
+): FFetch<PluginExtensions<TPlugins>> {
   const {
     timeout: clientDefaultTimeout = 5_000,
     retries: clientDefaultRetries = 0,
     retryDelay: clientDefaultRetryDelay = defaultDelay,
     shouldRetry: clientDefaultShouldRetry = defaultShouldRetry,
     hooks: clientDefaultHooks = {},
-    circuit: clientDefaultCircuit,
     fetchHandler,
-    dedupe = false,
-    dedupeHashFn = dedupeRequestHash,
-    dedupeTTL,
-    dedupeSweepInterval = 5000,
+    plugins: inputPlugins = [] as unknown as TPlugins,
   } = opts
 
-  const breaker = clientDefaultCircuit
-    ? new CircuitBreaker(
-        clientDefaultCircuit.threshold,
-        clientDefaultCircuit.reset
-      )
-    : null
+  const extensionDescriptors: PropertyDescriptorMap = Object.create(null)
 
-  if (
-    breaker &&
-    (clientDefaultHooks.onCircuitClose || clientDefaultHooks.onCircuitOpen)
-  ) {
-    breaker.setHooks({
-      onCircuitClose: clientDefaultHooks.onCircuitClose,
-      onCircuitOpen: clientDefaultHooks.onCircuitOpen,
+  const plugins = inputPlugins
+    .map((plugin, index) => ({ plugin, index }))
+    .sort((a, b) => {
+      const aOrder = a.plugin.order ?? 0
+      const bOrder = b.plugin.order ?? 0
+      if (aOrder !== bOrder) return aOrder - bOrder
+      return a.index - b.index
+    })
+    .map((entry) => entry.plugin)
+
+  for (const plugin of plugins) {
+    plugin.setup?.({
+      defineExtension: (key, descriptor) => {
+        const propertyKey = key as PropertyKey
+        if (propertyKey in extensionDescriptors) {
+          throw new Error(
+            `Plugin extension collision for property "${String(propertyKey)}"`
+          )
+        }
+        if ('get' in descriptor) {
+          extensionDescriptors[propertyKey] = {
+            get: descriptor.get,
+            enumerable: descriptor.enumerable ?? true,
+            configurable: false,
+          }
+          return
+        }
+        extensionDescriptors[propertyKey] = {
+          value: descriptor.value,
+          writable: false,
+          enumerable: descriptor.enumerable ?? true,
+          configurable: false,
+        }
+      },
     })
   }
 
@@ -96,57 +88,7 @@ export function createClient(opts: FFetchOptions = {}): FFetch {
     input: RequestInfo | URL,
     init: FFetchRequestInit = {}
   ) => {
-    // Deduplication logic
-    const effectiveDedupe =
-      typeof init.dedupe !== 'undefined' ? init.dedupe : dedupe
-    const effectiveDedupeHashFn = init.dedupeHashFn || dedupeHashFn
-    let dedupeKey: string | undefined
-
     let request = new Request(input, init)
-    if (effectiveDedupe) {
-      dedupeKey = effectiveDedupeHashFn({
-        method: request.method,
-        url: request.url,
-        body: init.body ?? null,
-        headers: request.headers,
-        signal:
-          init.signal === undefined || init.signal === null
-            ? undefined
-            : init.signal,
-        requestInit: init,
-        request,
-      })
-      if (dedupeKey) {
-        if (dedupeMap.has(dedupeKey)) {
-          return dedupeMap.get(dedupeKey)!.promise
-        }
-        let settled = false
-        let resolveFn: (value: Response | PromiseLike<Response>) => void
-        let rejectFn: (reason?: unknown) => void
-        const inFlightPromise = new Promise<Response>((resolve, reject) => {
-          resolveFn = (value) => {
-            if (!settled) {
-              settled = true
-              resolve(value)
-            }
-          }
-          rejectFn = (reason) => {
-            if (!settled) {
-              settled = true
-              reject(reason)
-            }
-          }
-        })
-        dedupeMap.set(dedupeKey, {
-          promise: inFlightPromise,
-          resolve: resolveFn!,
-          reject: rejectFn!,
-          createdAt: Date.now(),
-        })
-        // Start sweeper if needed
-        if (dedupeTTL) startDedupeSweeper()
-      }
-    }
 
     // Merge hooks: per-request hooks override client hooks, but fallback to client hooks
     const effectiveHooks = { ...clientDefaultHooks, ...(init.hooks || {}) }
@@ -155,6 +97,45 @@ export function createClient(opts: FFetchOptions = {}): FFetch {
     }
     await effectiveHooks.before?.(request)
 
+    // Determine retry config (per-request overrides client default)
+    const effectiveRetries = init.retries ?? clientDefaultRetries
+    const effectiveRetryDelay =
+      typeof init.retryDelay !== 'undefined'
+        ? init.retryDelay
+        : clientDefaultRetryDelay
+    const effectiveShouldRetry = init.shouldRetry ?? clientDefaultShouldRetry
+
+    // AbortSignal.timeout/any logic
+    const effectiveTimeout = init.timeout ?? clientDefaultTimeout
+    const userSignal = init.signal
+    const transformedSignal = request.signal
+
+    const pluginContext: PluginRequestContext = {
+      request,
+      init,
+      state: Object.create(null),
+      metadata: {
+        startedAt: Date.now(),
+        timeoutMs: effectiveTimeout,
+        signals: {
+          user:
+            userSignal === undefined || userSignal === null
+              ? undefined
+              : userSignal,
+          transformed: transformedSignal,
+        },
+        retry: {
+          configuredRetries: effectiveRetries,
+          configuredDelay: effectiveRetryDelay,
+          attempt: 0,
+        },
+      },
+    }
+
+    for (const plugin of plugins) {
+      await plugin.preRequest?.(pluginContext)
+    }
+
     // Determine throwOnHttpError (per-request overrides client default)
     const effectiveThrowOnHttpError =
       typeof init.throwOnHttpError !== 'undefined'
@@ -176,16 +157,13 @@ export function createClient(opts: FFetchOptions = {}): FFetch {
       return controller.signal
     }
 
-    // AbortSignal.timeout/any logic
-    const effectiveTimeout = init.timeout ?? clientDefaultTimeout
-    const userSignal = init.signal
-    const transformedSignal = request.signal
     let timeoutSignal: AbortSignal | undefined = undefined
     let combinedSignal: AbortSignal | undefined = undefined
     let controller: AbortController | undefined = undefined
 
     if (effectiveTimeout > 0) {
       timeoutSignal = createTimeoutSignal(effectiveTimeout)
+      pluginContext.metadata.signals.timeout = timeoutSignal
     }
 
     const signals: AbortSignal[] = []
@@ -207,19 +185,17 @@ export function createClient(opts: FFetchOptions = {}): FFetch {
       combinedSignal = AbortSignal.any(signals)
       controller = new AbortController()
     }
+    pluginContext.metadata.signals.combined = combinedSignal
 
     const retryWithHooks = async () => {
-      const effectiveRetries = init.retries ?? clientDefaultRetries
-      const effectiveRetryDelay =
-        typeof init.retryDelay !== 'undefined'
-          ? init.retryDelay
-          : clientDefaultRetryDelay
-      const effectiveShouldRetry = init.shouldRetry ?? clientDefaultShouldRetry
-
       let attempt = 0
       const shouldRetryWithHook = (ctx: import('./types').RetryContext) => {
         attempt = ctx.attempt
+        pluginContext.metadata.retry.attempt = attempt
+        pluginContext.metadata.retry.lastError = ctx.error
+        pluginContext.metadata.retry.lastResponse = ctx.response
         const retrying = effectiveShouldRetry(ctx)
+        pluginContext.metadata.retry.shouldRetryResult = retrying
         if (retrying && attempt <= effectiveRetries) {
           effectiveHooks.onRetry?.(
             request,
@@ -266,15 +242,10 @@ export function createClient(opts: FFetchOptions = {}): FFetch {
               const handler = init.fetchHandler ?? fetchHandler ?? fetch
               const response = await handler(reqWithSignal)
               lastResponse = response
-              if (
-                breaker &&
-                (response.status >= 500 || response.status === 429)
-              ) {
-                breaker.recordResult(response, undefined, request)
-              }
+              pluginContext.metadata.retry.lastResponse = response
               return response
             } catch (err) {
-              if (breaker) breaker.recordResult(undefined, err, request)
+              pluginContext.metadata.retry.lastError = err
               if (err instanceof DOMException && err.name === 'AbortError') {
                 if (
                   timeoutSignal?.aborted &&
@@ -326,6 +297,7 @@ export function createClient(opts: FFetchOptions = {}): FFetch {
         }
         return res
       } catch (err: unknown) {
+        pluginContext.metadata.retry.lastError = err
         if (lastResponse) {
           const resp = lastResponse as Response
           if (
@@ -374,38 +346,30 @@ export function createClient(opts: FFetchOptions = {}): FFetch {
       }
     }
 
-    const actualPromise = breaker
-      ? breaker.invoke(retryWithHooks).catch(async (err: unknown) => {
-          if (err instanceof CircuitOpenError) {
-            await effectiveHooks.onCircuitOpen?.(request)
-            await effectiveHooks.onError?.(request, err)
-            await effectiveHooks.onComplete?.(request, undefined, err)
-          } else {
-            await effectiveHooks.onError?.(request, err)
-            await effectiveHooks.onComplete?.(request, undefined, err)
-          }
-          throw err
-        })
-      : retryWithHooks()
+    const baseDispatch: PluginDispatch = async () => retryWithHooks()
 
-    // If deduplication is enabled and dedupeKey is set, resolve/reject the in-flight promise
-    if (effectiveDedupe && dedupeKey && dedupeMap.has(dedupeKey)) {
-      const entry = dedupeMap.get(dedupeKey)
-      if (entry) {
-        actualPromise.then(
-          (result) => entry.resolve(result),
-          (error) => entry.reject(error)
-        )
-        // Replace the placeholder with the actual promise for future requests, preserve createdAt
-        dedupeMap.set(dedupeKey, {
-          promise: actualPromise,
-          resolve: entry.resolve,
-          reject: entry.reject,
-          createdAt: entry.createdAt,
-        })
+    let dispatch = baseDispatch
+    for (let i = plugins.length - 1; i >= 0; i--) {
+      const plugin = plugins[i]
+      if (plugin.wrapDispatch) {
+        dispatch = plugin.wrapDispatch(dispatch)
       }
     }
 
+    const actualPromise = dispatch(pluginContext)
+      .then(async (response) => {
+        for (const plugin of plugins) {
+          await plugin.onSuccess?.(pluginContext, response)
+        }
+        return response
+      })
+      .catch(async (err: unknown) => {
+        for (const plugin of plugins) {
+          await plugin.onError?.(pluginContext, err)
+        }
+        throw err
+      })
+
     const pendingEntry: PendingRequest = {
       promise: actualPromise,
       request,
@@ -413,20 +377,15 @@ export function createClient(opts: FFetchOptions = {}): FFetch {
     }
     pendingRequests.push(pendingEntry)
 
-    return actualPromise.finally(() => {
+    return actualPromise.finally(async () => {
+      for (const plugin of plugins) {
+        await plugin.onFinally?.(pluginContext)
+      }
+
       const index = pendingRequests.indexOf(pendingEntry)
       if (index > -1) {
         pendingRequests.splice(index, 1)
       }
-      // Only delete dedupeMap entry if the promise is the same as the one in the map
-      if (
-        effectiveDedupe &&
-        dedupeKey &&
-        dedupeMap.get(dedupeKey)?.promise === actualPromise
-      ) {
-        dedupeMap.delete(dedupeKey)
-        stopDedupeSweeperIfIdle()
-      }
     })
   }
 
@@ -445,12 +404,7 @@ export function createClient(opts: FFetchOptions = {}): FFetch {
     configurable: false,
   })
 
-  Object.defineProperty(client, 'circuitOpen', {
-    get() {
-      return breaker ? breaker.open : false
-    },
-    enumerable: true,
-  })
+  Object.defineProperties(client, extensionDescriptors)
 
-  return client as FFetch
+  return client as FFetch<PluginExtensions<TPlugins>>
 }
diff --git a/src/hooks.ts b/src/hooks.ts
index 276e21e..129f145 100644
--- a/src/hooks.ts
+++ b/src/hooks.ts
@@ -10,8 +10,6 @@ export type Hooks = {
   ) => void | Promise<void>
   onTimeout?: (req: Request) => void | Promise<void>
   onAbort?: (req: Request) => void | Promise<void>
-  onCircuitOpen?: (req: Request) => void | Promise<void>
-  onCircuitClose?: (req: Request) => void | Promise<void>
   onComplete?: (
     req: Request,
     res?: Response,
diff --git a/src/index.ts b/src/index.ts
index e7c2a9d..815f2b0 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,8 +1,12 @@
 export type { FFetch, FFetchOptions } from './types'
-export type { DedupeHashParams } from './dedupeRequestHash'
 export type { Hooks } from './hooks'
+export type {
+  ClientPlugin,
+  PluginRequestContext,
+  PluginDispatch,
+  PluginSetupContext,
+} from './plugins'
 
-import { createClient } from './client'
 export { createClient } from './client'
 
 export {
@@ -12,5 +16,3 @@ export {
   RetryLimitError,
   NetworkError,
 } from './error'
-
-export default createClient
diff --git a/src/plugins.ts b/src/plugins.ts
new file mode 100644
index 0000000..a51b674
--- /dev/null
+++ b/src/plugins.ts
@@ -0,0 +1,83 @@
+// Plugin lifecycle contracts for control-flow features.
+// These are part of the public API for first-party and third-party plugins.
+export type PluginState = Record<string, unknown>
+export type PluginExtensionBase = Record<PropertyKey, unknown>
+
+type UnionToIntersection<U> = (
+  U extends unknown ? (arg: U) => void : never
+) extends (arg: infer I) => void
+  ? I
+  : never
+
+export type PluginExtensionOf<P> =
+  P extends ClientPlugin<infer TExtension> ? TExtension : Record<never, never>
+
+export type PluginExtensions<
+  TPlugins extends readonly ClientPlugin<PluginExtensionBase>[],
+> = Extract<UnionToIntersection<PluginExtensionOf<TPlugins[number]>>, object>
+
+export type PluginSetupContext<
+  TExtension extends PluginExtensionBase = Record<never, never>,
+> = {
+  defineExtension: <K extends keyof TExtension>(
+    key: K,
+    descriptor:
+      | { value: TExtension[K]; enumerable?: boolean }
+      | { get: () => TExtension[K]; enumerable?: boolean }
+  ) => void
+}
+
+export type PluginSignalMetadata = {
+  user?: AbortSignal
+  transformed?: AbortSignal
+  timeout?: AbortSignal
+  combined?: AbortSignal
+}
+
+export type PluginRetryMetadata = {
+  configuredRetries: number
+  configuredDelay:
+    | number
+    | ((ctx: {
+        attempt: number
+        request: Request
+        response?: Response
+        error?: unknown
+      }) => number)
+  attempt: number
+  shouldRetryResult?: boolean
+  lastError?: unknown
+  lastResponse?: Response
+}
+
+export type PluginRequestMetadata = {
+  startedAt: number
+  timeoutMs: number
+  signals: PluginSignalMetadata
+  retry: PluginRetryMetadata
+}
+
+export type PluginRequestContext = {
+  request: Request
+  init: RequestInit
+  state: PluginState
+  metadata: PluginRequestMetadata
+}
+
+export type PluginDispatch = (ctx: PluginRequestContext) => Promise<Response>
+
+export type ClientPlugin<
+  TExtension extends PluginExtensionBase = Record<never, never>,
+> = {
+  name: string
+  order?: number
+  setup?: (ctx: PluginSetupContext<TExtension>) => void
+  preRequest?: (ctx: PluginRequestContext) => void | Promise<void>
+  wrapDispatch?: (next: PluginDispatch) => PluginDispatch
+  onSuccess?: (
+    ctx: PluginRequestContext,
+    response: Response
+  ) => void | Promise<void>
+  onError?: (ctx: PluginRequestContext, error: unknown) => void | Promise<void>
+  onFinally?: (ctx: PluginRequestContext) => void | Promise<void>
+}
diff --git a/src/plugins/circuit.ts b/src/plugins/circuit.ts
new file mode 100644
index 0000000..16fdc9c
--- /dev/null
+++ b/src/plugins/circuit.ts
@@ -0,0 +1,101 @@
+import type { ClientPlugin } from '../plugins.js'
+import { CircuitOpenError } from '../error.js'
+
+export type CircuitPluginExtension = {
+  circuitOpen: boolean
+}
+
+export type CircuitPluginOptions = {
+  threshold: number
+  reset: number
+  onCircuitOpen?: (req: Request) => void | Promise<void>
+  onCircuitClose?: (req: Request) => void | Promise<void>
+  order?: number
+}
+
+export function circuitPlugin(
+  options: CircuitPluginOptions
+): ClientPlugin<CircuitPluginExtension> {
+  const {
+    threshold,
+    reset,
+    onCircuitOpen,
+    onCircuitClose,
+    order = 20,
+  } = options
+
+  let failures = 0
+  let nextAttempt = 0
+  let isOpen = false
+
+  const shouldCountFailure = (
+    response?: Response,
+    error?: unknown
+  ): boolean => {
+    if (error) {
+      return true
+    }
+    if (response && (response.status >= 500 || response.status === 429)) {
+      return true
+    }
+    return false
+  }
+
+  const onSuccess = async (req: Request) => {
+    const wasOpen = isOpen
+    failures = 0
+    if (wasOpen) {
+      isOpen = false
+      await onCircuitClose?.(req)
+    }
+  }
+
+  const onFailure = async (req: Request): Promise<boolean> => {
+    failures++
+    if (failures >= threshold) {
+      nextAttempt = Date.now() + reset
+      isOpen = true
+      await onCircuitOpen?.(req)
+      return true
+    }
+    return false
+  }
+
+  return {
+    name: 'circuit',
+    order,
+    setup: ({ defineExtension }) => {
+      defineExtension('circuitOpen', {
+        get: () => isOpen,
+        enumerable: true,
+      })
+    },
+    preRequest: async (ctx) => {
+      if (Date.now() < nextAttempt) {
+        await onCircuitOpen?.(ctx.request)
+        throw new CircuitOpenError('Circuit is open')
+      }
+    },
+    onSuccess: async (ctx, response) => {
+      if (shouldCountFailure(response, undefined)) {
+        const opened = await onFailure(ctx.request)
+        if (opened) {
+          throw new CircuitOpenError('Circuit is open')
+        }
+      } else {
+        await onSuccess(ctx.request)
+      }
+    },
+    onError: async (ctx, error) => {
+      if (error instanceof CircuitOpenError) {
+        return
+      }
+      if (shouldCountFailure(undefined, error)) {
+        const opened = await onFailure(ctx.request)
+        if (opened) {
+          throw new CircuitOpenError('Circuit is open')
+        }
+      }
+    },
+  }
+}
diff --git a/src/plugins/dedupe.ts b/src/plugins/dedupe.ts
new file mode 100644
index 0000000..b866d95
--- /dev/null
+++ b/src/plugins/dedupe.ts
@@ -0,0 +1,141 @@
+import type { ClientPlugin, PluginRequestContext } from '../plugins.js'
+import {
+  dedupeRequestHash,
+  type DedupeHashParams,
+} from '../dedupeRequestHash.js'
+
+type DedupeEntry = {
+  promise: Promise<Response>
+  resolve: (value: Response | PromiseLike<Response>) => void
+  reject: (reason?: unknown) => void
+  createdAt: number
+}
+
+export type DedupePluginOptions = {
+  hashFn?: (params: DedupeHashParams) => string | undefined
+  ttl?: number
+  sweepInterval?: number
+  order?: number
+}
+
+function contextToHashParams(ctx: PluginRequestContext): DedupeHashParams {
+  return {
+    method: ctx.request.method,
+    url: ctx.request.url,
+    body: (ctx.init.body ?? null) as DedupeHashParams['body'],
+    headers: ctx.request.headers,
+    signal:
+      ctx.init.signal === undefined || ctx.init.signal === null
+        ? undefined
+        : ctx.init.signal,
+    requestInit: ctx.init,
+    request: ctx.request,
+  }
+}
+
+export function dedupePlugin(options: DedupePluginOptions = {}): ClientPlugin {
+  const {
+    hashFn = dedupeRequestHash,
+    ttl,
+    sweepInterval = 5000,
+    order = 10,
+  } = options
+
+  const inFlight = new Map<string, DedupeEntry>()
+  let sweeper: ReturnType<typeof setInterval> | undefined
+
+  function startSweeper() {
+    if (sweeper || typeof ttl !== 'number' || ttl <= 0) return
+    sweeper = setInterval(() => {
+      const now = Date.now()
+      for (const [key, entry] of inFlight.entries()) {
+        if (now - entry.createdAt > ttl) {
+          inFlight.delete(key)
+        }
+      }
+      if (inFlight.size === 0 && sweeper) {
+        clearInterval(sweeper)
+        sweeper = undefined
+      }
+    }, sweepInterval)
+  }
+
+  function stopSweeperIfIdle() {
+    if (inFlight.size === 0 && sweeper) {
+      clearInterval(sweeper)
+      sweeper = undefined
+    }
+  }
+
+  return {
+    name: 'dedupe',
+    order,
+    wrapDispatch: (next) => async (ctx) => {
+      const key = hashFn(contextToHashParams(ctx))
+      ctx.state.dedupeKey = key
+
+      if (!key) {
+        return next(ctx)
+      }
+
+      const existing = inFlight.get(key)
+      if (existing) {
+        return existing.promise
+      }
+
+      let settled = false
+      let resolveFn: (value: Response | PromiseLike<Response>) => void
+      let rejectFn: (reason?: unknown) => void
+
+      const placeholder = new Promise<Response>((resolve, reject) => {
+        resolveFn = (value) => {
+          if (!settled) {
+            settled = true
+            resolve(value)
+          }
+        }
+        rejectFn = (reason) => {
+          if (!settled) {
+            settled = true
+            reject(reason)
+          }
+        }
+      })
+      // Internal placeholder can reject before a consumer attaches handlers.
+      // Mark it observed to avoid unhandled-rejection noise.
+      placeholder.catch(() => undefined)
+
+      inFlight.set(key, {
+        promise: placeholder,
+        resolve: resolveFn!,
+        reject: rejectFn!,
+        createdAt: Date.now(),
+      })
+      startSweeper()
+
+      const actualPromise = next(ctx)
+      const entry = inFlight.get(key)
+      if (entry) {
+        actualPromise.then(
+          (result) => entry.resolve(result),
+          (error) => entry.reject(error)
+        )
+        inFlight.set(key, {
+          ...entry,
+          promise: actualPromise,
+        })
+      }
+
+      return actualPromise.finally(() => {
+        const current = inFlight.get(key)
+        if (current?.promise === actualPromise) {
+          inFlight.delete(key)
+          stopSweeperIfIdle()
+        }
+      })
+    },
+  }
+}
+
+export { dedupeRequestHash }
+export type { DedupeHashParams }
diff --git a/src/timeout.ts b/src/timeout.ts
deleted file mode 100644
index 81ded92..0000000
--- a/src/timeout.ts
+++ /dev/null
@@ -1,12 +0,0 @@
-export const withTimeout = (
-  ms: number,
-  signal?: AbortSignal | null
-): AbortSignal => {
-  const ctrl = new AbortController()
-  const timer = setTimeout(() => ctrl.abort(), ms)
-  signal?.addEventListener('abort', () => {
-    clearTimeout(timer)
-    ctrl.abort()
-  })
-  return ctrl.signal
-}
diff --git a/src/types.ts b/src/types.ts
index a13c249..3c6aede 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -1,5 +1,5 @@
 import type { Hooks } from './hooks'
-import type { DedupeHashParams } from './dedupeRequestHash'
+import type { ClientPlugin, PluginExtensionBase } from './plugins'
 
 export interface RetryContext {
   attempt: number
@@ -8,33 +8,35 @@ export interface RetryContext {
   error?: unknown
 }
 
-export interface FFetchOptions {
+export interface CoreClientOptions {
   timeout?: number
   retries?: number
   retryDelay?: number | ((ctx: RetryContext) => number)
   shouldRetry?: (ctx: RetryContext) => boolean
   throwOnHttpError?: boolean
-  circuit?: { threshold: number; reset: number }
   hooks?: Hooks
   fetchHandler?: (
     input: RequestInfo | URL,
     init?: RequestInit
   ) => Promise<Response>
-  dedupe?: boolean
-  dedupeHashFn?: (params: DedupeHashParams) => string | undefined
-  dedupeTTL?: number
-  dedupeSweepInterval?: number
 }
 
-export type FFetch = {
+export interface FFetchOptions<
+  TPlugins extends
+    readonly ClientPlugin<PluginExtensionBase>[] = readonly ClientPlugin<PluginExtensionBase>[],
+> extends CoreClientOptions {
+  plugins?: TPlugins
+}
+
+export type FFetchRequestOptions = CoreClientOptions
+
+export type FFetch<TExtensions extends object = Record<never, never>> = {
   (input: RequestInfo | URL, init?: FFetchRequestInit): Promise<Response>
   pendingRequests: PendingRequest[]
   abortAll: () => void
-  // True if the circuit breaker is open (blocking requests), false otherwise
-  circuitOpen: boolean
-}
+} & TExtensions
 
-export interface FFetchRequestInit extends RequestInit, FFetchOptions {}
+export interface FFetchRequestInit extends RequestInit, FFetchRequestOptions {}
 
 export type PendingRequest = {
   promise: Promise<Response>
diff --git a/test/client.error.test.ts b/test/core/client.error.test.ts
similarity index 95%
rename from test/client.error.test.ts
rename to test/core/client.error.test.ts
index 1bb45bd..b1f3df9 100644
--- a/test/client.error.test.ts
+++ b/test/core/client.error.test.ts
@@ -22,7 +22,7 @@ it('retries on 400 if shouldRetry returns true', async () => {
   })
   const f = createClient({
     retries: 1,
-    shouldRetry: (ctx) => ctx.response?.status === 400,
+    shouldRetry: (ctx: RetryContext) => ctx.response?.status === 400,
   })
   const res = await f('https://test.com')
   expect(res.status).toBe(200)
@@ -68,7 +68,7 @@ it('throws CircuitOpenError if circuit opens due to repeated 5xx and throwOnHttp
   const f = createClient({
     throwOnHttpError: true,
     retries: 0,
-    circuit: { threshold: 2, reset: 100 },
+    plugins: [circuitPlugin({ threshold: 2, reset: 100 })],
   })
   // First two requests fail, opening the circuit
   await expect(f('https://test.com')).rejects.toThrow(HttpError)
@@ -130,17 +130,20 @@ it('throws AbortError or TimeoutError, not HttpError, if aborted/timed out and t
   const f2 = createClient({ throwOnHttpError: true, timeout: 10 })
   await expect(f2('https://test.com')).rejects.toThrow(TimeoutError)
 })
-import { HttpError } from '../src/error.js'
+import { HttpError } from '../../src/error.js'
 // Suppress unhandled promise rejections globally for this test file
 
 import { describe, it, expect, vi } from 'vitest'
-import createClient, {
+import {
+  createClient,
   TimeoutError,
   CircuitOpenError,
   AbortError,
   RetryLimitError,
   NetworkError,
-} from '../src/index.js'
+} from '../../src/index.js'
+import { circuitPlugin } from '../../src/plugins/circuit.js'
+import type { RetryContext } from '../../src/types.js'
 
 describe('Integration: Custom Errors', () => {
   it('throws HttpError on 4xx/5xx if throwOnHttpError is true (per-request)', async () => {
@@ -216,9 +219,9 @@ describe('Integration: Custom Errors', () => {
     global.fetch = vi.fn().mockRejectedValue(new Error('fail'))
     const f = createClient({
       retries: 0,
-      circuit: { threshold: 1, reset: 100 },
+      plugins: [circuitPlugin({ threshold: 1, reset: 100 })],
     })
-    await expect(f('https://example.com')).rejects.toThrow('fail')
+    await expect(f('https://example.com')).rejects.toThrow(CircuitOpenError)
     await expect(f('https://example.com')).rejects.toThrow(CircuitOpenError)
   })
 
@@ -346,14 +349,14 @@ describe('Advanced/Edge Cases: Custom Errors', () => {
     global.fetch = vi.fn().mockRejectedValue(new Error('fail'))
     const f = createClient({
       retries: 0,
-      circuit: { threshold: 2, reset: 100 },
+      plugins: [circuitPlugin({ threshold: 2, reset: 100 })],
     })
     await expect(f('https://example.com')).rejects.toThrow('fail')
     await expect(f('https://example.com')).rejects.toThrow(CircuitOpenError)
     await expect(f('https://example.com')).rejects.toThrow(CircuitOpenError)
     // Wait for reset
     await new Promise((r) => setTimeout(r, 120))
-    await expect(f('https://example.com')).rejects.toThrow('fail')
+    await expect(f('https://example.com')).rejects.toThrow(CircuitOpenError)
   })
 
   it('Error hooks receive correct error instance', async () => {
diff --git a/test/client.fetchHandler.test.ts b/test/core/client.fetchHandler.test.ts
similarity index 99%
rename from test/client.fetchHandler.test.ts
rename to test/core/client.fetchHandler.test.ts
index 34dc4c7..3c48b0d 100644
--- a/test/client.fetchHandler.test.ts
+++ b/test/core/client.fetchHandler.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from 'vitest'
-import { createClient } from '../src/client'
+import { createClient } from '../../src/client'
 
 // A mock fetch implementation for testing
 function mockFetch(
diff --git a/test/client.hooks.test.ts b/test/core/client.hooks.test.ts
similarity index 74%
rename from test/client.hooks.test.ts
rename to test/core/client.hooks.test.ts
index 463c3c7..7f3a4d8 100644
--- a/test/client.hooks.test.ts
+++ b/test/core/client.hooks.test.ts
@@ -1,6 +1,12 @@
 import { describe, it, expect, vi } from 'vitest'
-import { createClient } from '../src/client.js'
-import { CircuitOpenError } from '../src/error.js'
+import { createClient } from '../../src/client.js'
+import {
+  CircuitOpenError,
+  TimeoutError,
+  AbortError,
+  NetworkError,
+} from '../../src/error.js'
+import { circuitPlugin } from '../../src/plugins/circuit.js'
 
 describe('Hooks', () => {
   it('calls before, after, and onComplete hooks on success', async () => {
@@ -89,15 +95,111 @@ describe('Hooks', () => {
     expect(onAbort).toHaveBeenCalled()
   })
 
+  it('calls onError and onComplete with TimeoutError when timeout wins over a non-aborted user signal', async () => {
+    const onTimeout = vi.fn()
+    const onError = vi.fn()
+    const onComplete = vi.fn()
+    const userController = new AbortController()
+
+    global.fetch = vi.fn().mockImplementation(async (input) => {
+      const signal = input instanceof Request ? input.signal : undefined
+      return await new Promise((_resolve, reject) => {
+        if (signal && signal.aborted) {
+          reject(new DOMException('aborted', 'AbortError'))
+        } else if (signal) {
+          signal.addEventListener(
+            'abort',
+            () => reject(new DOMException('aborted', 'AbortError')),
+            { once: true }
+          )
+        }
+      })
+    })
+
+    const f = createClient({
+      timeout: 10,
+      hooks: { onTimeout, onError, onComplete },
+    })
+
+    await expect(
+      f('https://example.com/timeout-with-user-signal', {
+        signal: userController.signal,
+      })
+    ).rejects.toBeInstanceOf(TimeoutError)
+
+    expect(onTimeout).toHaveBeenCalled()
+    expect(onError).toHaveBeenCalledWith(
+      expect.any(Request),
+      expect.any(TimeoutError)
+    )
+    expect(onComplete).toHaveBeenCalledWith(
+      expect.any(Request),
+      undefined,
+      expect.any(TimeoutError)
+    )
+  })
+
+  it('calls onError and onComplete with AbortError when user aborts before dispatch', async () => {
+    const onAbort = vi.fn()
+    const onError = vi.fn()
+    const onComplete = vi.fn()
+
+    const controller = new AbortController()
+    controller.abort()
+
+    global.fetch = vi.fn().mockImplementation(async () => {
+      throw new Error('fetch should not be called')
+    })
+
+    const f = createClient({ hooks: { onAbort, onError, onComplete } })
+    await expect(
+      f('https://example.com/abort-before-dispatch', {
+        signal: controller.signal,
+      })
+    ).rejects.toBeInstanceOf(AbortError)
+
+    expect(onAbort).toHaveBeenCalled()
+    expect(onError).toHaveBeenCalledWith(
+      expect.any(Request),
+      expect.any(AbortError)
+    )
+    expect(onComplete).toHaveBeenCalledWith(
+      expect.any(Request),
+      undefined,
+      expect.any(AbortError)
+    )
+  })
+
+  it('calls onError and onComplete with NetworkError on network failures', async () => {
+    const onError = vi.fn()
+    const onComplete = vi.fn()
+
+    global.fetch = vi.fn().mockRejectedValue(new TypeError('failed to fetch'))
+
+    const f = createClient({ hooks: { onError, onComplete } })
+    await expect(f('https://example.com/network')).rejects.toBeInstanceOf(
+      NetworkError
+    )
+
+    expect(onError).toHaveBeenCalledWith(
+      expect.any(Request),
+      expect.any(NetworkError)
+    )
+    expect(onComplete).toHaveBeenCalledWith(
+      expect.any(Request),
+      undefined,
+      expect.any(NetworkError)
+    )
+  })
+
   it('calls onCircuitOpen hook when circuit breaker is open', async () => {
     const onCircuitOpen = vi.fn()
     global.fetch = vi.fn().mockRejectedValue(new Error('fail'))
     const f = createClient({
       retries: 0,
-      circuit: { threshold: 1, reset: 50 },
-      hooks: { onCircuitOpen },
+      plugins: [circuitPlugin({ threshold: 1, reset: 50, onCircuitOpen })],
     })
-    await expect(f('https://example.com')).rejects.toThrow('fail')
+    await expect(f('https://example.com')).rejects.toThrow('Circuit is open')
     await expect(f('https://example.com')).rejects.toThrow('Circuit is open')
     expect(onCircuitOpen).toHaveBeenCalled()
   })
@@ -274,7 +376,7 @@ describe('Hooks', () => {
     let onErrorCalled = false
     let onCompleteCalled = false
     const client = createClient({
-      circuit: { threshold: 1, reset: 10000 },
+      plugins: [circuitPlugin({ threshold: 1, reset: 10000 })],
       fetchHandler: () => {
         throw new Error('fail')
       },
@@ -288,12 +390,15 @@ describe('Hooks', () => {
       },
     })
     // First request fails, circuit opens
-    await expect(client('https://example.com')).rejects.toThrow()
+    await expect(client('https://example.com')).rejects.toThrow(
+      CircuitOpenError
+    )
     // Second request should trigger CircuitOpenError and hooks
     await expect(client('https://example.com')).rejects.toThrow(
       CircuitOpenError
     )
-    expect(onErrorCalled).toBe(true)
-    expect(onCompleteCalled).toBe(true)
+    // CircuitOpenError is generated by plugin control-flow, not core hook error mapping.
+    expect(onErrorCalled).toBe(false)
+    expect(onCompleteCalled).toBe(false)
   })
 })
diff --git a/test/client.override.test.ts b/test/core/client.override.test.ts
similarity index 96%
rename from test/client.override.test.ts
rename to test/core/client.override.test.ts
index ca99dc1..651c350 100644
--- a/test/client.override.test.ts
+++ b/test/core/client.override.test.ts
@@ -1,8 +1,8 @@
 // Suppress unhandled promise rejections globally for this test file
 
 import { describe, it, expect, vi, afterEach } from 'vitest'
-import type { FFetchRequestInit } from '../src/types.js'
-import { createClient } from '../src/client.js'
+import type { FFetchRequestInit } from '../../src/types.js'
+import { createClient } from '../../src/client.js'
 
 function mockFetchImpl(
   responseOrImpl: Response | ((..._args: unknown[]) => unknown),
diff --git a/test/client.pending.test.ts b/test/core/client.pending.test.ts
similarity index 99%
rename from test/client.pending.test.ts
rename to test/core/client.pending.test.ts
index 70d9338..2b8a7db 100644
--- a/test/client.pending.test.ts
+++ b/test/core/client.pending.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
-import createClient from '../src/index.js'
+import { createClient } from '../../src/index.js'
 
 describe('Pending Requests', () => {
   beforeEach(() => {
diff --git a/test/client.test.ts b/test/core/client.test.ts
similarity index 93%
rename from test/client.test.ts
rename to test/core/client.test.ts
index be8ceb6..e026dc9 100644
--- a/test/client.test.ts
+++ b/test/core/client.test.ts
@@ -1,7 +1,8 @@
 import { describe, it, expect, vi } from 'vitest'
 
-import { createClient } from '../src/client.js'
-import { defaultDelay } from '../src/retry.js'
+import { createClient } from '../../src/client.js'
+import { dedupePlugin } from '../../src/plugins/dedupe.js'
+import { defaultDelay } from '../../src/retry.js'
 
 describe('client hooks and error handling', () => {
   it('calls onTimeout and throws TimeoutError when timeout signal aborts', async () => {
@@ -75,11 +76,14 @@ describe('client branch coverage targets', () => {
   it('passes undefined signal to dedupeHashFn when init.signal is null', async () => {
     let seenSignal: AbortSignal | undefined = undefined
     const client = createClient({
-      dedupe: true,
-      dedupeHashFn: (params) => {
-        seenSignal = params.signal
-        return undefined
-      },
+      plugins: [
+        dedupePlugin({
+          hashFn: (params) => {
+            seenSignal = params.signal
+            return undefined
+          },
+        }),
+      ],
       fetchHandler: async () => new Response('ok', { status: 200 }),
     })
 
@@ -137,12 +141,14 @@ describe('client branch coverage targets', () => {
         throw new Error('fetch should not be called')
       })
 
-      const client = createClient({ timeout: 60 })
+      const onAbort = vi.fn()
+      const client = createClient({ timeout: 60, hooks: { onAbort } })
       await expect(
         client('https://example.com/fallback-user-abort', {
           signal: userController.signal,
         })
       ).rejects.toThrow('Request was aborted by user')
+      expect(onAbort).toHaveBeenCalled()
       expect(global.fetch).not.toHaveBeenCalled()
     } finally {
       AbortSignal.any = originalAny
@@ -344,7 +350,7 @@ describe('custom shouldRetry', () => {
   it('uses custom retry policy and retries only once', async () => {
     // custom policy that only retries on 503
     const customShouldRetry = (
-      ctx: import('../src/types').RetryContext
+      ctx: import('../../src/types').RetryContext
     ): boolean => {
       if (ctx.response) {
         return ctx.response.status === 503
@@ -486,7 +492,7 @@ it('dedupes identical requests and returns the same promise', async () => {
     return response
   })
 
-  const client = createClient({ dedupe: true })
+  const client = createClient({ plugins: [dedupePlugin()] })
   // Fire two requests with identical params
   const p1 = client('https://dedupe-test.com', { method: 'GET' })
   const p2 = client('https://dedupe-test.com', { method: 'GET' })
@@ -498,21 +504,20 @@ it('dedupes identical requests and returns the same promise', async () => {
   expect(await r1.text()).toBe('deduped')
 })
 
-it('dedupes and rejects identical requests together', async () => {
+it('dedupes identical requests that return HTTP error responses', async () => {
   let fetchCalls = 0
   global.fetch = vi.fn().mockImplementation(async () => {
     fetchCalls++
-    // Simulate network error
-    throw new Error('network fail')
+    return new Response('fail', { status: 500 })
   })
 
-  const client = createClient({ dedupe: true })
+  const client = createClient({ plugins: [dedupePlugin()] })
   // Fire two requests with identical params
   const p1 = client('https://dedupe-reject.com', { method: 'GET' })
   const p2 = client('https://dedupe-reject.com', { method: 'GET' })
-  // Both should reject with the same error
-  await expect(p1).rejects.toThrow('network fail')
-  await expect(p2).rejects.toThrow('network fail')
+  const [r1, r2] = await Promise.all([p1, p2])
+  expect(r1.status).toBe(500)
+  expect(r2.status).toBe(500)
   expect(fetchCalls).toBe(1)
 })
 
@@ -522,9 +527,7 @@ describe('dedupe cache TTL and sweeper', () => {
   it('should invalidate dedupe cache after TTL expires', async () => {
     let callCount = 0
     const client = createClient({
-      dedupe: true,
-      dedupeTTL: 50, // 50ms TTL
-      dedupeSweepInterval: 20,
+      plugins: [dedupePlugin({ ttl: 50, sweepInterval: 20 })],
       fetchHandler: async (_input: RequestInfo | URL) => {
         callCount++
         await delay(10)
@@ -555,9 +558,7 @@ describe('dedupe cache TTL and sweeper', () => {
       resolveFetch = res
     })
     const client = createClient({
-      dedupe: true,
-      dedupeTTL: 30,
-      dedupeSweepInterval: 10,
+      plugins: [dedupePlugin({ ttl: 30, sweepInterval: 10 })],
       fetchHandler: async () => {
         return await fetchPromise
       },
@@ -584,11 +585,9 @@ describe('dedupe cache TTL and sweeper', () => {
     expect(settled).toBe(true)
   })
 
-  it('should clean up dedupeMap and stop sweeper when empty', async () => {
+  it('should clean up dedupe entries when request settles', async () => {
     const client = createClient({
-      dedupe: true,
-      dedupeTTL: 20,
-      dedupeSweepInterval: 10,
+      plugins: [dedupePlugin({ ttl: 20, sweepInterval: 10 })],
       fetchHandler: async () => {
         return new Response('ok', { status: 200 })
       },
@@ -597,17 +596,14 @@ describe('dedupe cache TTL and sweeper', () => {
     await client('http://cleanup')
     await delay(30) // Wait for TTL and sweeper
 
-    // @ts-expect-error: access private for test
-    expect(client._dedupeMap?.size ?? 0).toBe(0)
-    // @ts-expect-error: access private for test
-    expect(client._dedupeSweeper).toBeUndefined()
+    // No direct plugin internals are exposed; this is validated by behavior.
+    await expect(client('http://cleanup')).resolves.toBeInstanceOf(Response)
   })
 
   it('should dedupe even if dedupeTTL is 0 (no expiry)', async () => {
     let callCount = 0
     const client = createClient({
-      dedupe: true,
-      dedupeTTL: 0,
+      plugins: [dedupePlugin({ ttl: 0 })],
       fetchHandler: async () => {
         callCount++
         return new Response('ok', { status: 200 })
diff --git a/test/client.circuitbreaker.test.ts b/test/integration/client.circuitbreaker.test.ts
similarity index 65%
rename from test/client.circuitbreaker.test.ts
rename to test/integration/client.circuitbreaker.test.ts
index c8c666d..5d84230 100644
--- a/test/client.circuitbreaker.test.ts
+++ b/test/integration/client.circuitbreaker.test.ts
@@ -1,8 +1,8 @@
 import { describe, it, expect, vi } from 'vitest'
 
-import { createClient } from '../src/client.js'
-import { CircuitOpenError, RetryLimitError } from '../src/index.js'
-import { CircuitBreaker } from '../src/circuit.js'
+import { createClient } from '../../src/client.js'
+import { CircuitOpenError, RetryLimitError } from '../../src/index.js'
+import { circuitPlugin } from '../../src/plugins/circuit.js'
 
 it('calls onCircuitOpen and onCircuitClose hooks appropriately', async () => {
   let openCalled = false
@@ -18,15 +18,18 @@ it('calls onCircuitOpen and onCircuitClose hooks appropriately', async () => {
 
   const client = createClient({
     retries: 0,
-    circuit: { threshold: 2, reset: 100 },
-    hooks: {
-      onCircuitOpen: () => {
-        openCalled = true
-      },
-      onCircuitClose: (_req) => {
-        closeCalled = true
-      },
-    },
+    plugins: [
+      circuitPlugin({
+        threshold: 2,
+        reset: 100,
+        onCircuitOpen: () => {
+          openCalled = true
+        },
+        onCircuitClose: () => {
+          closeCalled = true
+        },
+      }),
+    ],
   })
 
   // First two requests fail, opening the circuit
@@ -38,55 +41,17 @@ it('calls onCircuitOpen and onCircuitClose hooks appropriately', async () => {
   // Wait for reset period
   await new Promise((resolve) => setTimeout(resolve, 120))
 
-  // Third request should still fail (circuit not reset yet)
-  await expect(client('https://example.com')).rejects.toThrow(RetryLimitError)
-  // Optionally, if circuit is open, use CircuitOpenError
-  // await expect(client('https://example.com')).rejects.toThrow(CircuitOpenError)
-  // Circuit should not be closed yet
-  expect(closeCalled).toBe(false)
+  // Third request succeeds after reset period and should close circuit.
+  await expect(client('https://example.com')).resolves.toBeInstanceOf(Response)
+  expect(closeCalled).toBe(true)
 })
 
-describe('CircuitBreaker', () => {
-  it('recordResult returns false for success and triggers onCircuitClose with last success request', async () => {
-    const onCircuitClose = vi.fn()
-    const breaker = new CircuitBreaker(1, 10)
-    breaker.setHooks({ onCircuitClose })
-
-    const openReq = new Request('https://open.example.com')
-    const successReq = new Request('https://success.example.com')
-
-    // Open breaker with a counted failure
-    expect(breaker.recordResult(undefined, new Error('fail'), openReq)).toBe(
-      true
-    )
-    expect(breaker.open).toBe(true)
-
-    // Success should set lastSuccessRequest, close breaker, and return false
-    expect(
-      breaker.recordResult(
-        new Response('ok', { status: 200 }),
-        undefined,
-        successReq
-      )
-    ).toBe(false)
-    expect(breaker.open).toBe(false)
-    expect(onCircuitClose).toHaveBeenCalledTimes(1)
-    expect(onCircuitClose).toHaveBeenCalledWith(successReq)
-  })
-
-  it('recordResult success path works without request and still returns false', () => {
-    const breaker = new CircuitBreaker(2, 10)
-    expect(breaker.recordResult(new Response('ok', { status: 200 }))).toBe(
-      false
-    )
-    expect(breaker.open).toBe(false)
-  })
-
+describe('circuit plugin', () => {
   it('exposes open state via getter', async () => {
     global.fetch = vi.fn().mockRejectedValue(new Error('fail'))
     const client = createClient({
       retries: 0,
-      circuit: { threshold: 3, reset: 100 },
+      plugins: [circuitPlugin({ threshold: 3, reset: 100 })],
     })
     // Initially, circuit should be closed
     expect(client.circuitOpen).toBe(false)
@@ -95,7 +60,7 @@ describe('CircuitBreaker', () => {
     expect(client.circuitOpen).toBe(false)
     // Second failure
     await expect(client('https://test.com')).rejects.toThrow('fail')
-    expect(client.circuitOpen).toBe(true)
+    expect(client.circuitOpen).toBe(false)
     // Third failure opens the circuit
     await expect(client('https://test.com')).rejects.toThrow(CircuitOpenError)
     expect(client.circuitOpen).toBe(true)
@@ -104,8 +69,8 @@ describe('CircuitBreaker', () => {
     expect(client.circuitOpen).toBe(true)
     // Wait for reset
     await new Promise((r) => setTimeout(r, 200))
-    // After reset, next call tries again (and fails)
-    await expect(client('https://test.com')).rejects.toThrow('fail')
+    // After reset, next call tries again and fails into open state.
+    await expect(client('https://test.com')).rejects.toThrow(CircuitOpenError)
     expect(client.circuitOpen).toBe(true)
     // Simulate a successful request
     global.fetch = vi.fn().mockResolvedValue(new Response('ok'))
@@ -121,7 +86,7 @@ describe('CircuitBreaker', () => {
 
     const f = createClient({
       retries: 0,
-      circuit: { threshold: 2, reset: 200 },
+      plugins: [circuitPlugin({ threshold: 2, reset: 200 })],
     })
 
     // First two calls fail and increment failures
@@ -134,16 +99,16 @@ describe('CircuitBreaker', () => {
     // Wait for reset timeout
     await new Promise((r) => setTimeout(r, 220)).catch(() => {})
 
-    // Next call should try again (and fail)
-    await expect(f('https://example.com')).rejects.toThrow('fail')
-    expect(global.fetch).toHaveBeenCalledTimes(2)
+    // Next call should try again and fail into open state.
+    await expect(f('https://example.com')).rejects.toThrow(CircuitOpenError)
+    expect(global.fetch).toHaveBeenCalledTimes(3)
   })
 
   it('does not open circuit if threshold not reached', async () => {
     global.fetch = vi.fn().mockRejectedValue(new Error('fail'))
     const f = createClient({
       retries: 0,
-      circuit: { threshold: 3, reset: 100 },
+      plugins: [circuitPlugin({ threshold: 3, reset: 100 })],
     })
     // Only 2 failures, threshold is 3
     await expect(f('https://a.com')).rejects.toThrow('fail')
@@ -156,7 +121,7 @@ describe('CircuitBreaker', () => {
     global.fetch = vi.fn().mockRejectedValue(new Error('fail'))
     const f = createClient({
       retries: 0,
-      circuit: { threshold: 2, reset: 1000 },
+      plugins: [circuitPlugin({ threshold: 2, reset: 1000 })],
     })
     await expect(f('https://b.com')).rejects.toThrow('fail')
     await expect(f('https://b.com')).rejects.toThrow(CircuitOpenError)
@@ -172,15 +137,15 @@ describe('CircuitBreaker', () => {
     })
     const f = createClient({
       retries: 0,
-      circuit: { threshold: 1, reset: 100 },
+      plugins: [circuitPlugin({ threshold: 1, reset: 100 })],
     })
-    await expect(f('https://c.com')).rejects.toThrow('fail')
+    await expect(f('https://c.com')).rejects.toThrow(CircuitOpenError)
     // Circuit opens
     await expect(f('https://c.com')).rejects.toThrow(CircuitOpenError)
     // Wait for reset
     await new Promise((r) => setTimeout(r, 120)).catch(() => {})
-    // Should try again
-    await expect(f('https://c.com')).rejects.toThrow('fail')
+    // Should try again and fail into open state again
+    await expect(f('https://c.com')).rejects.toThrow(CircuitOpenError)
     expect(callCount).toBe(2)
   })
 
@@ -192,7 +157,7 @@ describe('CircuitBreaker', () => {
     })
     const f = createClient({
       retries: 0,
-      circuit: { threshold: 2, reset: 100 },
+      plugins: [circuitPlugin({ threshold: 2, reset: 100 })],
     })
     // Two failures
     await expect(f('https://d.com')).rejects.toThrow('fail')
diff --git a/test/integration/plugins.integration.test.ts b/test/integration/plugins.integration.test.ts
new file mode 100644
index 0000000..b5e6d17
--- /dev/null
+++ b/test/integration/plugins.integration.test.ts
@@ -0,0 +1,123 @@
+import { describe, it, expect, vi } from 'vitest'
+
+import { createClient } from '../../src/client.js'
+import { CircuitOpenError } from '../../src/error.js'
+import { dedupePlugin } from '../../src/plugins/dedupe.js'
+import { circuitPlugin } from '../../src/plugins/circuit.js'
+import type { ClientPlugin } from '../../src/plugins.js'
+
+describe('plugin ordering and interactions', () => {
+  it('applies plugin order before registration order in preRequest lifecycle', async () => {
+    const calls: string[] = []
+
+    const late: ClientPlugin = {
+      name: 'late',
+      order: 50,
+      preRequest: () => {
+        calls.push('late')
+      },
+    }
+
+    const early: ClientPlugin = {
+      name: 'early',
+      order: -10,
+      preRequest: () => {
+        calls.push('early')
+      },
+    }
+
+    const tieA: ClientPlugin = {
+      name: 'tie-a',
+      order: 10,
+      preRequest: () => {
+        calls.push('tie-a')
+      },
+    }
+
+    const tieB: ClientPlugin = {
+      name: 'tie-b',
+      order: 10,
+      preRequest: () => {
+        calls.push('tie-b')
+      },
+    }
+
+    const client = createClient({
+      plugins: [late, tieA, early, tieB],
+      fetchHandler: async () => new Response('ok', { status: 200 }),
+    })
+
+    await client('https://example.com/order')
+    expect(calls).toEqual(['early', 'tie-a', 'tie-b', 'late'])
+  })
+
+  it('dedupe + circuit interaction: one network call can trip circuit based on plugin callbacks', async () => {
+    global.fetch = vi
+      .fn()
+      .mockResolvedValue(new Response('fail', { status: 500 }))
+
+    const plugins = [
+      dedupePlugin(),
+      circuitPlugin({ threshold: 2, reset: 200 }),
+    ] as const
+
+    const client = createClient({
+      retries: 0,
+      plugins,
+    })
+
+    const results = await Promise.allSettled([
+      client('https://example.com/shared-failure'),
+      client('https://example.com/shared-failure'),
+    ])
+
+    const fulfilled = results.filter((r) => r.status === 'fulfilled')
+    const rejected = results.filter((r) => r.status === 'rejected')
+
+    expect(fulfilled).toHaveLength(1)
+    expect(
+      (fulfilled[0] as PromiseFulfilledResult<Response>).value.status
+    ).toBe(500)
+    expect(rejected).toHaveLength(1)
+    expect((rejected[0] as PromiseRejectedResult).reason).toBeInstanceOf(
+      CircuitOpenError
+    )
+    expect(global.fetch).toHaveBeenCalledTimes(1)
+
+    expect(client.circuitOpen).toBe(true)
+    await expect(
+      client('https://example.com/blocked-after-shared')
+    ).rejects.toThrow(CircuitOpenError)
+  })
+
+  it('custom plugin can override dedupe key before dedupe runs when order is lower', async () => {
+    const forceUniquePlugin: ClientPlugin = {
+      name: 'force-unique-key',
+      order: 0,
+      preRequest: (ctx) => {
+        ctx.state.unique = crypto.randomUUID()
+      },
+      wrapDispatch: (next) => async (ctx) => {
+        const originalUrl = new URL(ctx.request.url)
+        originalUrl.searchParams.set('nonce', String(ctx.state.unique))
+        ctx.request = new Request(originalUrl.toString(), ctx.request)
+        return next(ctx)
+      },
+    }
+
+    global.fetch = vi
+      .fn()
+      .mockResolvedValue(new Response('ok', { status: 200 }))
+
+    const client = createClient({
+      plugins: [forceUniquePlugin, dedupePlugin()],
+    })
+
+    await Promise.all([
+      client('https://example.com/custom-order'),
+      client('https://example.com/custom-order'),
+    ])
+
+    expect(global.fetch).toHaveBeenCalledTimes(2)
+  })
+})
diff --git a/test/plugins/circuit.plugin.test.ts b/test/plugins/circuit.plugin.test.ts
new file mode 100644
index 0000000..d604604
--- /dev/null
+++ b/test/plugins/circuit.plugin.test.ts
@@ -0,0 +1,120 @@
+import { describe, it, expect, vi } from 'vitest'
+
+import { createClient } from '../../src/client.js'
+import { CircuitOpenError } from '../../src/error.js'
+import { circuitPlugin } from '../../src/plugins/circuit.js'
+
+describe('circuit plugin parity', () => {
+  it('opens after threshold failures and blocks while open', async () => {
+    global.fetch = vi
+      .fn()
+      .mockResolvedValue(new Response('fail', { status: 500 }))
+
+    const client = createClient({
+      retries: 0,
+      plugins: [circuitPlugin({ threshold: 2, reset: 1000 })],
+    })
+
+    const r1 = await client('https://example.com/circuit-1')
+    await expect(client('https://example.com/circuit-2')).rejects.toThrow(
+      CircuitOpenError
+    )
+
+    expect(r1.status).toBe(500)
+    expect(client.circuitOpen).toBe(true)
+
+    await expect(client('https://example.com/circuit-3')).rejects.toThrow(
+      CircuitOpenError
+    )
+  })
+
+  it('resets after timeout and closes on a successful probe', async () => {
+    let failMode = true
+    global.fetch = vi.fn().mockImplementation(async () => {
+      if (failMode) {
+        return new Response('fail', { status: 500 })
+      }
+      return new Response('ok', { status: 200 })
+    })
+
+    const onCircuitOpen = vi.fn()
+    const onCircuitClose = vi.fn()
+
+    const client = createClient({
+      retries: 0,
+      plugins: [
+        circuitPlugin({
+          threshold: 1,
+          reset: 50,
+          onCircuitOpen,
+          onCircuitClose,
+        }),
+      ],
+    })
+
+    await expect(client('https://example.com/open')).rejects.toThrow(
+      CircuitOpenError
+    )
+    expect(client.circuitOpen).toBe(true)
+    expect(onCircuitOpen).toHaveBeenCalledTimes(1)
+
+    await expect(client('https://example.com/blocked')).rejects.toThrow(
+      CircuitOpenError
+    )
+    expect(onCircuitOpen).toHaveBeenCalledTimes(2)
+
+    await new Promise((resolve) => setTimeout(resolve, 70))
+
+    failMode = false
+    const recovered = await client('https://example.com/recover')
+
+    expect(recovered.status).toBe(200)
+    expect(client.circuitOpen).toBe(false)
+    expect(onCircuitClose).toHaveBeenCalledTimes(1)
+  })
+
+  it('treats HTTP 429 as a circuit failure signal', async () => {
+    global.fetch = vi
+      .fn()
+      .mockResolvedValue(new Response('rate limited', { status: 429 }))
+
+    const client = createClient({
+      retries: 0,
+      plugins: [circuitPlugin({ threshold: 1, reset: 200 })],
+    })
+
+    await expect(client('https://example.com/rate-limit')).rejects.toThrow(
+      CircuitOpenError
+    )
+    expect(client.circuitOpen).toBe(true)
+
+    await expect(client('https://example.com/rate-limit-2')).rejects.toThrow(
+      CircuitOpenError
+    )
+  })
+
+  it('resets failure counter after success before reaching threshold', async () => {
+    const statuses = [500, 200, 500, 200]
+    global.fetch = vi.fn().mockImplementation(async () => {
+      const status = statuses.shift() ?? 200
+      return new Response(String(status), { status })
+    })
+
+    const client = createClient({
+      retries: 0,
+      plugins: [circuitPlugin({ threshold: 2, reset: 500 })],
+    })
+
+    await client('https://example.com/mix-1')
+    expect(client.circuitOpen).toBe(false)
+
+    await client('https://example.com/mix-2')
+    expect(client.circuitOpen).toBe(false)
+
+    await client('https://example.com/mix-3')
+    expect(client.circuitOpen).toBe(false)
+
+    await client('https://example.com/mix-4')
+    expect(client.circuitOpen).toBe(false)
+  })
+})
diff --git a/test/plugins/dedupe.plugin.test.ts b/test/plugins/dedupe.plugin.test.ts
new file mode 100644
index 0000000..3469f73
--- /dev/null
+++ b/test/plugins/dedupe.plugin.test.ts
@@ -0,0 +1,208 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+
+import { createClient } from '../../src/client.js'
+import { HttpError } from '../../src/error.js'
+import { dedupePlugin } from '../../src/plugins/dedupe.js'
+
+function createDeferred<T>() {
+  let resolve!: (value: T | PromiseLike<T>) => void
+  let reject!: (reason?: unknown) => void
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  return { promise, resolve, reject }
+}
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+describe('dedupe plugin parity', () => {
+  it('dedupes concurrent requests with the same key', async () => {
+    let calls = 0
+    global.fetch = vi.fn().mockImplementation(async () => {
+      calls++
+      await new Promise((resolve) => setTimeout(resolve, 10))
+      return new Response('ok', { status: 200 })
+    })
+
+    const client = createClient({
+      plugins: [dedupePlugin()],
+    })
+
+    const p1 = client('https://example.com/dedupe')
+    const p2 = client('https://example.com/dedupe')
+    const [r1, r2] = await Promise.all([p1, p2])
+
+    expect(r1.status).toBe(200)
+    expect(r2.status).toBe(200)
+    expect(calls).toBe(1)
+  })
+
+  it('does not dedupe when hashFn returns undefined', async () => {
+    global.fetch = vi
+      .fn()
+      .mockResolvedValue(new Response('ok', { status: 200 }))
+
+    const client = createClient({
+      plugins: [
+        dedupePlugin({
+          hashFn: () => undefined,
+        }),
+      ],
+    })
+
+    await Promise.all([
+      client('https://example.com/no-dedupe'),
+      client('https://example.com/no-dedupe'),
+    ])
+
+    expect(global.fetch).toHaveBeenCalledTimes(2)
+  })
+
+  it('evicts stale dedupe key after TTL while preserving in-flight promises', async () => {
+    vi.useFakeTimers()
+
+    const resolvers: Array<(value: Response) => void> = []
+    global.fetch = vi.fn().mockImplementation(() => {
+      return new Promise<Response>((resolve) => {
+        resolvers.push(resolve)
+      })
+    })
+
+    const client = createClient({
+      plugins: [dedupePlugin({ ttl: 10, sweepInterval: 5 })],
+    })
+
+    const p1 = client('https://example.com/ttl')
+    const fetchMock = global.fetch as ReturnType<typeof vi.fn>
+    let p2 = client('https://example.com/ttl')
+    for (let i = 0; i < 10 && fetchMock.mock.calls.length < 2; i++) {
+      await vi.advanceTimersByTimeAsync(5)
+      p2 = client('https://example.com/ttl')
+    }
+
+    expect(global.fetch).toHaveBeenCalledTimes(2)
+    expect(resolvers).toHaveLength(2)
+
+    resolvers[0](new Response('first', { status: 200 }))
+    resolvers[1](new Response('second', { status: 200 }))
+
+    await expect(p1).resolves.toBeInstanceOf(Response)
+    await expect(p2).resolves.toBeInstanceOf(Response)
+  })
+
+  it('keeps dedupe key while within TTL window', async () => {
+    vi.useFakeTimers()
+
+    let resolver: ((value: Response) => void) | undefined
+    global.fetch = vi.fn().mockImplementation(() => {
+      return new Promise<Response>((resolve) => {
+        resolver = resolve
+      })
+    })
+
+    const client = createClient({
+      plugins: [dedupePlugin({ ttl: 100, sweepInterval: 10 })],
+    })
+
+    const p1 = client('https://example.com/ttl-window')
+    await vi.advanceTimersByTimeAsync(40)
+    const p2 = client('https://example.com/ttl-window')
+
+    expect(global.fetch).toHaveBeenCalledTimes(1)
+
+    resolver?.(new Response('ok', { status: 200 }))
+    await Promise.all([p1, p2])
+  })
+
+  it('supports custom hash function parity behavior', async () => {
+    const seenMethods: string[] = []
+
+    global.fetch = vi
+      .fn()
+      .mockResolvedValue(new Response('ok', { status: 200 }))
+
+    const client = createClient({
+      plugins: [
+        dedupePlugin({
+          hashFn: (params) => {
+            seenMethods.push(params.method)
+            return `${params.method}:${params.url}`
+          },
+        }),
+      ],
+    })
+
+    await Promise.all([
+      client('https://example.com/hash', { method: 'POST', body: 'a' }),
+      client('https://example.com/hash', { method: 'POST', body: 'b' }),
+    ])
+
+    expect(global.fetch).toHaveBeenCalledTimes(1)
+    expect(seenMethods).toEqual(['POST', 'POST'])
+  })
+
+  it('passes through a defined signal to custom hashFn', async () => {
+    const controller = new AbortController()
+    let seenSignal: AbortSignal | undefined
+
+    global.fetch = vi
+      .fn()
+      .mockResolvedValue(new Response('ok', { status: 200 }))
+
+    const client = createClient({
+      plugins: [
+        dedupePlugin({
+          hashFn: (params) => {
+            seenSignal = params.signal
+            return undefined
+          },
+        }),
+      ],
+    })
+
+    await client('https://example.com/with-signal', {
+      signal: controller.signal,
+    })
+
+    expect(seenSignal).toBe(controller.signal)
+  })
+
+  it('propagates one underlying failure to all deduped callers', async () => {
+    const deferred = createDeferred<Response>()
+    global.fetch = vi.fn().mockReturnValue(deferred.promise)
+
+    const client = createClient({
+      throwOnHttpError: true,
+      retries: 0,
+      plugins: [dedupePlugin()],
+    })
+
+    const p1 = client('https://example.com/reject')
+    const p2 = client('https://example.com/reject')
+
+    const handled1 = p1.then(
+      () => ({ ok: true as const }),
+      (error) => ({ ok: false as const, error })
+    )
+    const handled2 = p2.then(
+      () => ({ ok: true as const }),
+      (error) => ({ ok: false as const, error })
+    )
+
+    deferred.resolve(new Response('boom', { status: 500 }))
+
+    const [r1, r2] = await Promise.all([handled1, handled2])
+    expect(r1.ok).toBe(false)
+    expect(r2.ok).toBe(false)
+    if (!r1.ok) {
+      expect(r1.error).toBeInstanceOf(HttpError)
+    }
+    if (!r2.ok) {
+      expect(r2.error).toBeInstanceOf(HttpError)
+    }
+    expect(global.fetch).toHaveBeenCalledTimes(1)
+  })
+})
diff --git a/test/dedupeRequestHash.test.ts b/test/plugins/dedupeRequestHash.test.ts
similarity index 97%
rename from test/dedupeRequestHash.test.ts
rename to test/plugins/dedupeRequestHash.test.ts
index c94b462..5eb1636 100644
--- a/test/dedupeRequestHash.test.ts
+++ b/test/plugins/dedupeRequestHash.test.ts
@@ -1,5 +1,8 @@
 import { describe, it, expect } from 'vitest'
-import { dedupeRequestHash, DedupeHashParams } from '../src/dedupeRequestHash'
+import {
+  dedupeRequestHash,
+  DedupeHashParams,
+} from '../../src/dedupeRequestHash'
 
 describe('dedupeRequestHash', () => {
   it('returns undefined for FormData body', () => {
diff --git a/test/plugins/plugin.pipeline.test.ts b/test/plugins/plugin.pipeline.test.ts
new file mode 100644
index 0000000..4a727b3
--- /dev/null
+++ b/test/plugins/plugin.pipeline.test.ts
@@ -0,0 +1,244 @@
+import { describe, it, expect } from 'vitest'
+
+import { createClient } from '../../src/client.js'
+import type { ClientPlugin } from '../../src/plugins.js'
+import { RetryLimitError } from '../../src/error.js'
+
+describe('plugin pipeline', () => {
+  it('runs lifecycle hooks in sorted plugin order on success', async () => {
+    const events: string[] = []
+
+    const pluginA: ClientPlugin = {
+      name: 'a',
+      order: 20,
+      preRequest: () => {
+        events.push('a.pre')
+      },
+      wrapDispatch: (next) => async (ctx) => {
+        events.push('a.wrap.before')
+        const res = await next(ctx)
+        events.push('a.wrap.after')
+        return res
+      },
+      onSuccess: () => {
+        events.push('a.success')
+      },
+      onFinally: () => {
+        events.push('a.finally')
+      },
+    }
+
+    const pluginB: ClientPlugin = {
+      name: 'b',
+      order: 10,
+      preRequest: () => {
+        events.push('b.pre')
+      },
+      wrapDispatch: (next) => async (ctx) => {
+        events.push('b.wrap.before')
+        const res = await next(ctx)
+        events.push('b.wrap.after')
+        return res
+      },
+      onSuccess: () => {
+        events.push('b.success')
+      },
+      onFinally: () => {
+        events.push('b.finally')
+      },
+    }
+
+    const client = createClient({
+      plugins: [pluginA, pluginB],
+      fetchHandler: async () => {
+        events.push('fetch')
+        return new Response('ok', { status: 200 })
+      },
+    })
+
+    const response = await client('https://example.com/pipeline-success')
+    expect(response.status).toBe(200)
+
+    expect(events).toEqual([
+      'b.pre',
+      'a.pre',
+      'b.wrap.before',
+      'a.wrap.before',
+      'fetch',
+      'a.wrap.after',
+      'b.wrap.after',
+      'b.success',
+      'a.success',
+      'b.finally',
+      'a.finally',
+    ])
+  })
+
+  it('runs onError and onFinally in sorted order on failure', async () => {
+    const events: string[] = []
+
+    const first: ClientPlugin = {
+      name: 'first',
+      order: 1,
+      onError: (_ctx, error) => {
+        events.push(`first.error.${error instanceof RetryLimitError}`)
+      },
+      onFinally: () => {
+        events.push('first.finally')
+      },
+    }
+
+    const second: ClientPlugin = {
+      name: 'second',
+      order: 2,
+      onError: (_ctx, error) => {
+        events.push(`second.error.${error instanceof RetryLimitError}`)
+      },
+      onFinally: () => {
+        events.push('second.finally')
+      },
+    }
+
+    const client = createClient({
+      retries: 0,
+      plugins: [second, first],
+      fetchHandler: async () => {
+        throw new Error('boom')
+      },
+    })
+
+    await expect(client('https://example.com/pipeline-error')).rejects.toThrow(
+      RetryLimitError
+    )
+
+    expect(events).toEqual([
+      'first.error.true',
+      'second.error.true',
+      'first.finally',
+      'second.finally',
+    ])
+  })
+
+  it('supports plugin-defined client extensions via setup', async () => {
+    const plugin: ClientPlugin<{ pluginName: string; dynamicValue: number }> = {
+      name: 'extension-plugin',
+      setup: ({ defineExtension }) => {
+        defineExtension('pluginName', { value: 'extension-plugin' })
+        defineExtension('dynamicValue', {
+          get: () => 42,
+        })
+      },
+    }
+
+    const client = createClient({
+      plugins: [plugin],
+      fetchHandler: async () => new Response('ok', { status: 200 }),
+    })
+
+    expect(client.pluginName).toBe('extension-plugin')
+    expect(client.dynamicValue).toBe(42)
+    await expect(
+      client('https://example.com/extensions')
+    ).resolves.toBeInstanceOf(Response)
+  })
+
+  it('throws when multiple plugins define the same extension key', () => {
+    const first: ClientPlugin<{ conflict: number }> = {
+      name: 'first',
+      setup: ({ defineExtension }) => {
+        defineExtension('conflict', { value: 1 })
+      },
+    }
+
+    const second: ClientPlugin<{ conflict: number }> = {
+      name: 'second',
+      setup: ({ defineExtension }) => {
+        defineExtension('conflict', { value: 2 })
+      },
+    }
+
+    expect(() => {
+      createClient({ plugins: [first, second] })
+    }).toThrow('Plugin extension collision for property "conflict"')
+  })
+
+  it('keeps registration order when plugin order values are equal', async () => {
+    const calls: string[] = []
+
+    const first: ClientPlugin = {
+      name: 'first',
+      order: 5,
+      preRequest: () => {
+        calls.push('first')
+      },
+    }
+
+    const second: ClientPlugin = {
+      name: 'second',
+      order: 5,
+      preRequest: () => {
+        calls.push('second')
+      },
+    }
+
+    const client = createClient({
+      plugins: [first, second],
+      fetchHandler: async () => new Response('ok', { status: 200 }),
+    })
+
+    await client('https://example.com/equal-order')
+    expect(calls).toEqual(['first', 'second'])
+  })
+
+  it('passes mutable plugin state across lifecycle handlers in one request', async () => {
+    const lifecycle: string[] = []
+
+    const plugin: ClientPlugin = {
+      name: 'state-check',
+      preRequest: (ctx) => {
+        ctx.state.correlationId = 'abc-123'
+        lifecycle.push('pre')
+      },
+      wrapDispatch: (next) => async (ctx) => {
+        lifecycle.push(`wrap:${String(ctx.state.correlationId)}`)
+        return next(ctx)
+      },
+      onSuccess: (ctx) => {
+        lifecycle.push(`success:${String(ctx.state.correlationId)}`)
+      },
+    }
+
+    const client = createClient({
+      plugins: [plugin],
+      fetchHandler: async () => new Response('ok', { status: 200 }),
+    })
+
+    await client('https://example.com/state')
+    expect(lifecycle).toEqual(['pre', 'wrap:abc-123', 'success:abc-123'])
+  })
+
+  it('invokes plugin hooks for each request context independently', async () => {
+    const requestIds: string[] = []
+
+    const plugin: ClientPlugin = {
+      name: 'request-scope',
+      preRequest: (ctx) => {
+        ctx.state.requestId = crypto.randomUUID()
+      },
+      onFinally: (ctx) => {
+        requestIds.push(String(ctx.state.requestId))
+      },
+    }
+
+    const client = createClient({
+      plugins: [plugin],
+      fetchHandler: async () => new Response('ok', { status: 200 }),
+    })
+
+    await client('https://example.com/one')
+    await client('https://example.com/two')
+
+    expect(requestIds).toHaveLength(2)
+    expect(requestIds[0]).not.toBe(requestIds[1])
+  })
+})
diff --git a/test/timeout.test.ts b/test/timeout.test.ts
deleted file mode 100644
index acd9594..0000000
--- a/test/timeout.test.ts
+++ /dev/null
@@ -1,38 +0,0 @@
-import { describe, it, expect } from 'vitest'
-import { withTimeout } from '../src/timeout.js'
-
-function delay(ms: number) {
-  return new Promise((resolve) => setTimeout(resolve, ms))
-}
-
-describe('withTimeout', () => {
-  it('aborts after the specified timeout', async () => {
-    const signal = withTimeout(20)
-    expect(signal.aborted).toBe(false)
-    await delay(25)
-    expect(signal.aborted).toBe(true)
-  })
-
-  it('aborts if parent signal is aborted', async () => {
-    const parent = new AbortController()
-    const signal = withTimeout(50, parent.signal)
-    expect(signal.aborted).toBe(false)
-    parent.abort()
-    expect(signal.aborted).toBe(true)
-  })
-
-  it('does not abort before timeout if parent is not aborted', async () => {
-    const signal = withTimeout(30)
-    expect(signal.aborted).toBe(false)
-    await delay(10)
-    expect(signal.aborted).toBe(false)
-  })
-
-  it('clears timer if parent aborts before timeout', async () => {
-    const parent = new AbortController()
-    const signal = withTimeout(50, parent.signal)
-    parent.abort()
-    await delay(60)
-    expect(signal.aborted).toBe(true)
-  })
-})
diff --git a/tsup.config.ts b/tsup.config.ts
index 8f1b0c5..bdc727d 100644
--- a/tsup.config.ts
+++ b/tsup.config.ts
@@ -2,7 +2,7 @@ import { defineConfig } from 'tsup'
 
 export default defineConfig([
   {
-    entry: ['src/index.ts'],
+    entry: ['src/index.ts', 'src/plugins/dedupe.ts', 'src/plugins/circuit.ts'],
     format: ['esm', 'cjs'],
     dts: true,
     minify: false,

From 1428df68b5267a68d16bdba6b005ff03aae58b59 Mon Sep 17 00:00:00 2001
From: gkoos <gabor.koos@gmail.com>
Date: Sat, 14 Mar 2026 03:48:25 +0000
Subject: [PATCH 2/2] Documentation errors fixed

---
 README.md             |  8 ++---
 docs/advanced.md      |  5 +--
 docs/api.md           |  4 +--
 docs/compatibility.md | 81 ++++++++++++++++++++++---------------------
 docs/examples.md      |  2 +-
 docs/hooks.md         | 36 ++++++++++++++-----
 docs/migration.md     |  6 +---
 7 files changed, 80 insertions(+), 62 deletions(-)

diff --git a/README.md b/README.md
index 4cffbae..16ba654 100644
--- a/README.md
+++ b/README.md
@@ -156,12 +156,12 @@ Native `fetch`'s controversial behavior of not throwing errors for HTTP error st
 
 ## Environment Requirements
 
-`ffetch` requires modern AbortSignal APIs:
+`ffetch` works best with native `AbortSignal.any` support:
 
-- **Node.js 20.6+** (for AbortSignal.any)
-- **Modern browsers** (Chrome 117+, Firefox 117+, Safari 17+, Edge 117+)
+- **Node.js 20.6+** (native `AbortSignal.any`)
+- **Modern browsers with `AbortSignal.any`** (for example: Chrome 117+, Firefox 117+, Safari 17+, Edge 117+)
 
-If your environment does not support `AbortSignal.any` (Node.js < 20.6, older browsers), you **must install a polyfill** before using ffetch. See the [compatibility guide](./docs/compatibility.md) for instructions.
+If your environment does not support `AbortSignal.any` (Node.js < 20.6, older browsers), you can still use ffetch by installing an `AbortSignal.any` polyfill. `AbortSignal.timeout` is optional because ffetch includes an internal timeout fallback. See the [compatibility guide](./docs/compatibility.md) for instructions.
 
 **Custom fetch support:**
 You can pass any fetch-compatible implementation (native fetch, node-fetch, undici, SvelteKit, Next.js, Nuxt, or a polyfill) via the `fetchHandler` option. This makes ffetch fully compatible with SSR, edge, metaframework environments, custom backends, and test runners.
diff --git a/docs/advanced.md b/docs/advanced.md
index 2c53a28..d3b1a6f 100644
--- a/docs/advanced.md
+++ b/docs/advanced.md
@@ -126,7 +126,7 @@ You can provide a function for `retryDelay` that receives a context object:
 ```typescript
 const client = createClient({
   retryDelay: ({ attempt, request, response, error }) => {
-    // attempt: number (starts at 2 for first retry)
+    // attempt: number (starts at 1 for first retry decision)
     // request: Request
     // response: Response | undefined
     // error: unknown
@@ -198,13 +198,14 @@ This is useful for:
 - Implementing custom fallback or degraded mode logic
 - Integrating with dashboards or metrics
 
-> **Note:** If the client is not configured with a circuit breaker (`circuit` option omitted), `client.circuitOpen` will always be `false` and the property is inert.
+> **Note:** `client.circuitOpen` is provided by `circuitPlugin`. If that plugin is not installed, this extension is not available on the client.
 
 ### How it Works
 
 - When the number of consecutive failures reaches the `threshold`, the circuit "opens" and all further requests fail fast with a `CircuitOpenError`
 - After the `reset` period (in milliseconds), the circuit "closes" and requests are allowed again
 - If a request succeeds, the failure count resets
+- If `onCircuitOpen` is configured, it runs both when the circuit opens and when requests are blocked while it is already open
 
 ### Configuration
 
diff --git a/docs/api.md b/docs/api.md
index a5505c0..1a92531 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -116,7 +116,7 @@ See [plugins.md](./plugins.md) for full lifecycle, ordering, extensions, and adv
 
 ### Removed Legacy Options (Breaking)
 
-The following top-level options were removed and now throw a migration error if passed:
+The following top-level options were removed:
 
 - `dedupe`
 - `dedupeHashFn`
@@ -164,5 +164,5 @@ type FFetch = {
 ### Notes
 
 - Signal combination (user, timeout, transformRequest) requires `AbortSignal.any`.
-- The first retry attempt uses `attempt = 2`.
+- The first retry decision uses `attempt = 1`.
 - Plugin order is deterministic: first by `order`, then by registration order.
diff --git a/docs/compatibility.md b/docs/compatibility.md
index 38120cd..098e4eb 100644
--- a/docs/compatibility.md
+++ b/docs/compatibility.md
@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-`ffetch` requires modern AbortSignal APIs, specifically `AbortSignal.timeout` and **AbortSignal.any**. Signal combination requires `AbortSignal.any` (native or polyfill).
+`ffetch` can work without native `AbortSignal.timeout` because it has an internal timeout fallback. Signal combination requires **`AbortSignal.any`** (native or polyfill).
 
 ## Node.js Support
 
@@ -13,7 +13,8 @@
 
 ### Polyfills for Older Versions
 
-For older Node.js versions, you must install a polyfill for both `AbortSignal.timeout` and `AbortSignal.any`:
+For older Node.js versions, you must install a polyfill for `AbortSignal.any`.
+`AbortSignal.timeout` polyfill is optional because `ffetch` has an internal timeout fallback:
 
 ```bash
 npm install abortcontroller-polyfill abort-controller-x
@@ -22,10 +23,10 @@ npm install abortcontroller-polyfill abort-controller-x
 Then ensure the APIs are available globally before importing `ffetch`:
 
 ```javascript
-// Option 1: abortcontroller-polyfill (for AbortSignal.timeout)
+// Optional: abortcontroller-polyfill (for native-style AbortSignal.timeout)
 require('abortcontroller-polyfill/dist/polyfill-patch-fetch')
 
-// Option 2: abort-controller-x (for AbortSignal.any)
+// Required when AbortSignal.any is missing
 import 'abort-controller-x/polyfill'
 
 // Now you can use ffetch
@@ -43,50 +44,60 @@ await client('https://api.example.com') // Works
 await client('http://localhost:3000') // Works
 ```
 
-#### Custom Agents
+#### Custom Node Connection Agent
 
 ```javascript
 import https from 'https'
+import fetch from 'node-fetch'
 
-const client = createClient()
-
-// Use custom HTTPS agent
-await client('https://api.example.com', {
-  agent: new https.Agent({
-    keepAlive: true,
-    timeout: 5000,
-  }),
+const agent = new https.Agent({
+  keepAlive: true,
+  timeout: 5000,
 })
+
+// Wrap your fetch implementation and inject transport-specific options there.
+const fetchWithAgent = (input, init) => fetch(input, { ...init, agent })
+
+const client = createClient({ fetchHandler: fetchWithAgent })
+
+await client('https://api.example.com')
 ```
 
+`agent` is fetch-implementation-specific and not part of standard `RequestInit`. Prefer configuring it inside `fetchHandler`.
+
 #### Self-signed Certificates (Development)
 
 ```javascript
 // For development only - never use in production
 process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0'
 
-// Better approach: use custom agent
+// Better approach: configure a custom agent in fetchHandler
 import https from 'https'
+import fetch from 'node-fetch'
 
 const agent = new https.Agent({
   rejectUnauthorized: false,
 })
 
-await client('https://localhost:8443', { agent })
+const client = createClient({
+  fetchHandler: (input, init) => fetch(input, { ...init, agent }),
+})
+
+await client('https://localhost:8443')
 ```
 
 ## Browser Support
 
 ### Modern Browsers (Recommended)
 
-- **Chrome 88+**: Full support
-- **Firefox 89+**: Full support
-- **Safari 15.4+**: Full support
-- **Edge 88+**: Full support
+- **Chrome 117+**: Native support for required AbortSignal APIs
+- **Firefox 117+**: Native support for required AbortSignal APIs
+- **Safari 17+**: Native support for required AbortSignal APIs
+- **Edge 117+**: Native support for required AbortSignal APIs
 
 ### Legacy Browser Support
 
-For older browsers, you need polyfills for `AbortSignal.timeout` and `AbortSignal.any`:
+Older browsers can still work when `AbortSignal.any` is polyfilled. `AbortSignal.timeout` polyfill is optional:
 
 ```html
 <!-- Include polyfills before your app -->
@@ -95,7 +106,7 @@ For older browsers, you need polyfills for `AbortSignal.timeout` and `AbortSigna
 
 <!-- Your app -->
 <script type="module">
-  import createClient from 'https://unpkg.com/@fetchkit/ffetch/dist/index.min.js'
+  import { createClient } from 'https://unpkg.com/@fetchkit/ffetch/dist/index.min.js'
   // ... your code
 </script>
 ```
@@ -118,8 +129,8 @@ self.addEventListener('fetch', async (event) => {
 #### Web Workers
 
 ```javascript
-// Works in web workers
-importScripts('https://unpkg.com/@fetchkit/ffetch/dist/index.min.js')
+// Use a module worker and import the ESM build
+import { createClient } from 'https://unpkg.com/@fetchkit/ffetch/dist/index.min.js'
 
 const client = createClient()
 self.postMessage(await client('/api/data').then((r) => r.json()))
@@ -202,10 +213,6 @@ function checkCompatibility() {
     throw new Error('AbortSignal not supported. Please add a polyfill.')
   }
 
-  if (typeof AbortSignal.timeout !== 'function') {
-    throw new Error('AbortSignal.timeout not supported. Please add a polyfill.')
-  }
-
   if (typeof AbortSignal.any !== 'function') {
     throw new Error(
       'AbortSignal.any is required for combining multiple signals. Please install a polyfill.'
@@ -234,22 +241,16 @@ const client = createClient({
 
 ```html
 <script type="module">
-  import createClient from 'https://unpkg.com/@fetchkit/ffetch/dist/index.min.js'
+  import { createClient } from 'https://unpkg.com/@fetchkit/ffetch/dist/index.min.js'
 
   const client = createClient()
   const data = await client('/api/data').then((r) => r.json())
 </script>
 ```
 
-### UMD (Legacy)
+### UMD
 
-```html
-<script src="https://unpkg.com/@fetchkit/ffetch/dist/index.umd.js"></script>
-<script>
-  const client = FFetch.createClient()
-  // ... use client
-</script>
-```
+`ffetch` does not currently publish a UMD build. Use the ESM build shown above (or import from the package in a bundler/runtime environment).
 
 ## Framework Integration
 
@@ -355,7 +356,7 @@ onUnmounted(() => {
 
 ### SSR Frameworks: SvelteKit, Next.js, Nuxt
 
-For SvelteKit, Next.js, and Nuxt, you must pass the exact fetch instance provided by the framework in your handler or context. This is not the global fetch, and the parameter name may vary (often `fetch`, but check your framework docs).
+For SvelteKit, Next.js, and Nuxt, it is recommended to pass the fetch instance provided by the framework in your handler or context for SSR-safe behavior. The parameter name may vary (often `fetch`, but check your framework docs).
 
 **SvelteKit example:**
 
@@ -392,7 +393,7 @@ export default async function handler(request) {
 }
 ```
 
-> Always use the fetch instance provided by the framework in your handler/context, not the global fetch. The parameter name may vary, but it is always context-specific.
+> Recommended: use the fetch instance provided by the framework in handler/context code. ffetch also supports any fetch-compatible implementation and falls back to global fetch when no `fetchHandler` is provided.
 
 ## Troubleshooting
 
@@ -401,7 +402,9 @@ export default async function handler(request) {
 #### "AbortSignal.timeout is not a function"
 
 ```
-Solution: Add a polyfill for AbortSignal.timeout
+ffetch has an internal fallback, so this is usually non-fatal.
+
+Optional: add a polyfill for AbortSignal.timeout
 npm install abortcontroller-polyfill
 ```
 
diff --git a/docs/examples.md b/docs/examples.md
index 6540045..f2b84f0 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -24,7 +24,7 @@ if (client.circuitOpen) {
 }
 ```
 
-// If the client is not configured with a circuit breaker, client.circuitOpen will always be false.
+// `client.circuitOpen` is available when `circuitPlugin(...)` is installed on the client.
 
 ### Simple HTTP Client
 
diff --git a/docs/hooks.md b/docs/hooks.md
index edca6cb..9d1efe7 100644
--- a/docs/hooks.md
+++ b/docs/hooks.md
@@ -4,15 +4,29 @@ Hooks allow you to observe, log, or modify the request/response lifecycle. All h
 
 ## Lifecycle Hooks
 
+In this document, **core hooks** means the callbacks under `createClient({ hooks: ... })`:
+
+- `before`
+- `after`
+- `onError`
+- `onRetry`
+- `onTimeout`
+- `onAbort`
+- `onComplete`
+- `transformRequest`
+- `transformResponse`
+
+These are separate from plugin lifecycle callbacks (`setup`, `preRequest`, `wrapDispatch`, `onSuccess`, `onError`, `onFinally`).
+
 ### Available Hooks
 
 - `before(req)`: Called before each request is sent
 - `after(req, res)`: Called after a successful response
-- `onError(req, err)`: Called when a request fails with any error
+- `onError(req, err)`: Called when core request execution fails (before plugin post-processing)
 - `onRetry(req, attempt, err, res)`: Called before each retry attempt
 - `onTimeout(req)`: Called when a request times out
 - `onAbort(req)`: Called when a request is aborted by the user
-- `onComplete(req, res, err)`: Called after every request, whether it succeeded or failed
+- `onComplete(req, res, err)`: Called when core request execution completes (last among core hooks)
 
 ### Basic Hooks Example
 
@@ -256,10 +270,11 @@ const client = createClient({
   retries: 3,
   hooks: {
     onRetry: async (req, attempt, err, res) => {
-      console.log(`Retry ${attempt - 1}/3 for ${req.url}`)
+      // `attempt` is zero-based in onRetry (0 = first retry)
+      console.log(`Retry ${attempt + 1}/3 for ${req.url}`)
 
       // Add exponential backoff delay
-      const delay = Math.min(1000 * Math.pow(2, attempt - 2), 10000)
+      const delay = Math.min(1000 * Math.pow(2, attempt), 10000)
       console.log(`Waiting ${delay}ms before retry...`)
       await new Promise((resolve) => setTimeout(resolve, delay))
 
@@ -276,7 +291,7 @@ const client = createClient({
 
 ### onCircuitOpen
 
-Called when the circuit transitions to open after consecutive failures. Receives the request that triggered the open event.
+Called when the circuit opens after consecutive failures, and also when a request is blocked while the circuit is already open. Receives the request associated with that event.
 
 Signature: `(req: Request) => void | Promise<void>`
 
@@ -313,17 +328,20 @@ When a request is made, hooks execute in this order:
 3. **Request is sent**
 4. `transformResponse` - Modify the incoming response (if successful)
 5. `after` - Called after successful response
-6. `onComplete` - Always called last
+6. `onComplete` - Last among core hooks
 
 If an error occurs or retry is needed:
 
-1. `onError` - Called on any error
+1. `onError` - Called on core execution errors
 2. `onRetry` - Called before retry attempts
 3. `onTimeout` - Called on timeout errors
 4. `onAbort` - Called on abort errors
-5. Plugin `onCircuitOpen` callback - Called when circuit breaker transitions to open
+5. Plugin `onCircuitOpen` callback - Called when circuit opens, and on blocked requests while already open
 6. Plugin `onCircuitClose` callback - Called when circuit breaker transitions to closed
-7. `onComplete` - Always called last
+7. `onComplete` - Last among core hooks
+
+After core hooks run, plugin lifecycle callbacks may still run (for example plugin `onSuccess`, `onError`, and `onFinally`).
+If a plugin throws after core completion, core `onError` is not re-fired and core `onComplete` may already have run with success arguments.
 
 ## Per-Request Hooks
 
diff --git a/docs/migration.md b/docs/migration.md
index fa98d3d..8cd9c5c 100644
--- a/docs/migration.md
+++ b/docs/migration.md
@@ -127,11 +127,7 @@ const plugins = [circuitPlugin({ threshold: 5, reset: 30_000 })] as const
 const client = createClient({ plugins })
 ```
 
-## 6) Runtime Guard for Legacy Options
-
-v5 throws a clear runtime error if removed options are still present in client options or per-request init.
-
-## 7) Quick Upgrade Checklist
+## 6) Quick Upgrade Checklist
 
 1. Replace default root import with named root import.
 2. Add plugin imports from: