@budarin/pluggable-serviceworker 1.2.1 → 1.5.1

package/README.md

@@ -24,7 +24,7 @@
 ### ⚡ **Оптимизированная логика выполнения**
 
 - **Параллельно** для `install`, `activate`, `message`, `sync` - независимые задачи выполняются одновременно
-- **Последовательно** для `fetch`, `push` - первый успешный результат прерывает цепочку
+- **Последовательно** для `fetch` — первый успешный результат прерывает цепочку; для `push` — вызываются все плагины, показывается уведомление по каждому payload (или одно от библиотеки только когда **все** плагины вернули `undefined`)
 - **Производительность** - правильный выбор стратегии для каждого типа события
 
 ### 🛡️ **Централизованная обработка ошибок**
@@ -59,84 +59,103 @@ pnpm add @budarin/pluggable-serviceworker
 ```typescript
 // sw.js
 import {
-    initServiceWorker,
+    type PluginContext,
     type ServiceWorkerPlugin,
-    type SwContext,
+    initServiceWorker,
 } from '@budarin/pluggable-serviceworker';
 
-// Контекст: список ассетов для precache и имя кеша
-interface PrecacheAndServeContext extends SwContext {
-    assets: string[];
+function precacheAndServePlugin(config: {
     cacheName: string;
+    assets: string[];
+}): ServiceWorkerPlugin<PluginContext> {
+    const { cacheName, assets } = config;
+
+    return {
+        name: 'precache-and-serve',
+
+        install: async (_event, logger) => {
+            if (import.meta.env.DEV) {
+                logger.debug('precache-and-serve: cache assets');
+            }
+
+            const cache = await caches.open(cacheName);
+            await cache.addAll(assets);
+        },
+
+        fetch: async (event, logger) => {
+            const cache = await caches.open(cacheName);
+            const asset = await cache.match(event.request);
+
+            if (!asset && import.meta.env.DEV) {
+                logger.debug(
+                    `precache-and-serve: asset ${event.request.url} not found in cache!`
+                );
+            }
+
+            return asset ?? undefined;
+        },
+    };
 }
 
-const precacheAndServePlugin: ServiceWorkerPlugin<PrecacheAndServeContext> = {
-    name: 'precache-and-serve',
+initServiceWorker([
+    precacheAndServePlugin({
+        cacheName: 'my-cache-v1',
+        assets: ['/', '/styles.css', '/script.js'],
+    }),
+]);
+```
 
-    install: async (_event, context) => {
-        const cache = await caches.open(context.cacheName);
-        await cache.addAll(context.assets);
-    },
+**Важно:**
 
-    fetch: async (event, context) => {
-        const cache = await caches.open(context.cacheName);
-        return cache.match(event.request) ?? undefined;
-    },
-};
+- для `fetch` плагину не нужно самому вызывать `fetch(event.request)` — если все плагины вернули `undefined`, фреймворк сам идёт в сеть.
+- конфиг плагина задаётся по месту вызова фабрики; в `options` только `logger?` и `onError?`.
 
-// TypeScript проверит, что в options есть assets и cacheName
-initServiceWorker([precacheAndServePlugin], {
-    logger: console,
-    assets: ['/', '/styles.css', '/script.js'],
-    cacheName: 'my-cache-v1',
-});
-```
+### Фабрика плагинов
 
-**Важно:** для `fetch` плагину не нужно самому вызывать `fetch(event.request)`, если все плагины вернули `undefined` - фреймворк сам выполняет запрос в сеть. Во все обработчики плагинов вторым аргументом передаётся **контекст** — те же данные, что вы передали в `initServiceWorker`.
+**Плагин** — это объект с полем `name` и опциональными обработчиками (`install`, `fetch`, `activate` и т.д.). В массив `initServiceWorker(plugins, options)` передаются именно такие объекты.
 
-## Демо
+**Фабрика плагина** — функция, которая принимает конфиг и возвращает плагин (объект). Например: `precache(config)`, `serveFromCache(config)` или собственная `precacheAndServePlugin(config)` из примера выше. Конфиг задаётся по месту вызова фабрики; в общий `options` попадают только `logger?` и `onError?`.
 
-В папке [demo/](demo/) — приложение **React + Vite** с пресетом **offlineFirst** и типовым сервис-воркером **activateOnSignal**. Запуск из корня: `pnpm install && pnpm build`, затем `cd demo && pnpm install && pnpm run dev`. Подробности и ссылки на публичные песочницы (StackBlitz, CodeSandbox) — в [demo/README.md](demo/README.md).
+## Демо
 
-[Open in StackBlitz](https://stackblitz.com/github/budarin/pluggable-serviceworker/tree/master/demo) · [Open in CodeSandbox](https://codesandbox.io/s/github/budarin/pluggable-serviceworker/tree/master/demo)
+В папке [demo/](demo/) — приложение **React + Vite** с пресетом **offlineFirst** и типовым сервис-воркером **activateOnSignal**. Запуск из корня: `pnpm start`. Подробности — в [demo/README.md](demo/README.md).
 
 ## `initServiceWorker(plugins, options)`
 
-`initServiceWorker` — точка входа: она регистрирует обработчики событий Service Worker (`install`, `activate`, `fetch`, …) и прогоняет их через список плагинов.
+`initServiceWorker` — точка входа: регистрирует обработчики событий Service Worker (`install`, `activate`, `fetch`, …) и прогоняет их через список плагинов.
 
-- `plugins`: массив плагинов
-- `options`: один общий объект с настройками/данными, который будет доступен плагинам как **контекст**
+- **`plugins`** — массив плагинов (объектов). Плагины с конфигом получаются вызовом **фабрик** по месту использования (см. раздел «Фабрика плагинов»).
+- **`options`** — только `logger?` и `onError?`. В обработчики плагинов вторым аргументом передаётся **logger** (из `options` или `console`).
 
 **Пример:**
 
 ```typescript
-initServiceWorker([myPlugin], {
-    logger: console,
-    // ... тут будут поля контекста, которые требуют плагины ...
-});
+initServiceWorker(
+    [
+        precache({ cacheName: 'v1', assets: ['/'] }),
+        serveFromCache({ cacheName: 'v1' }),
+    ],
+    { logger: serverLogger, onError: handleError }
+);
 ```
 
-## ⚙️ Конфигурация и контекст (options)
+## ⚙️ Опции initServiceWorker (logger, onError)
 
-Функция `initServiceWorker` принимает второй параметр `options` типа `ServiceWorkerInitOptions` (контекст для плагинов + `onError` для библиотеки). В обработчики плагинов вторым аргументом передаётся **контекст** — часть этого объекта без `onError` (тип контекста — `SwContext` и ваши поля; при типизированных плагинах — пересечение требуемых ими полей).
+Второй параметр `options` типа `ServiceWorkerInitOptions`: в нём только `logger?` и `onError?`. В обработчики плагинов передаётся только **logger** (второй аргумент); если `logger` не указан, используется `console`. Поле `onError` нужно только библиотеке, в плагины не передаётся.
+
+Тип `PluginContext` в API используется для типизации (содержит `logger?`); «богатого контекста» плагинам не передаётся.
 
 ```typescript
-interface SwContext {
+interface PluginContext {
     logger?: Logger; // по умолчанию console
-    // сюда можно добавлять свои поля: version, assets, cacheName и т.д.
 }
 
-// В initServiceWorker передаётся ServiceWorkerInitOptions = SwContext + onError:
-interface ServiceWorkerInitOptions extends SwContext {
+interface ServiceWorkerInitOptions extends PluginContext {
     onError?: (error, event, errorType?) => void; // только для библиотеки, в плагины не передаётся
 }
 ```
 
-В тип контекста, который видят плагины, входит только `SwContext` и ваши поля; `onError` в этот тип не входит и используется только библиотекой.
-
-Формируйте объект `options` в своём сервис-воркере (контекст для плагинов + при необходимости `onError`) и передавайте его в `initServiceWorker`. В плагины передаётся тот же объект как контекст — плагины получают доступ к полям контекста, а `onError` остаётся внутренним делом библиотеки.
-
-### Поля конфигурации
+### Поля options
 
 #### `logger?: Logger` (опциональное)
 
@@ -155,17 +174,15 @@ interface Logger {
 **Пример:**
 
 ```typescript
-const logger = console; // Использование стандартного console
-
 const options = {
-    logger,
+    logger: customLogger, // Использование кастомного логгера
     // или
     logger: {
-        trace: (...data) => customLog('TRACE', ...data),
-        debug: (...data) => customLog('DEBUG', ...data),
-        info: (...data) => customLog('INFO', ...data),
-        warn: (...data) => customLog('WARN', ...data),
-        error: (...data) => customLog('ERROR', ...data),
+        trace: (...data) => customLogger('TRACE', ...data),
+        debug: (...data) => customLogger('DEBUG', ...data),
+        info: (...data) => customLogger('INFO', ...data),
+        warn: (...data) => customLogger('WARN', ...data),
+        error: (...data) => customLogger('ERROR', ...data),
     },
 };
 ```
@@ -186,7 +203,7 @@ const options = {
 
 ```typescript
 // Без onError - ошибки будут проигнорированы
-initServiceWorker([cachePlugin], {});
+initServiceWorker([cachePlugin]);
 
 // С onError - ошибки будут обработаны
 initServiceWorker([cachePlugin], {
@@ -270,74 +287,63 @@ initServiceWorker(
 
 ## 🔌 Интерфейс плагина
 
-Каждый плагин реализует интерфейс `ServiceWorkerPlugin<C>`, где `C extends SwContext` — тип контекста, который плагин ожидает. Во все обработчики вторым аргументом передаётся контекст (те же данные, что в `options` при инициализации, без `onError`).
+Плагин — объект, реализующий интерфейс `ServiceWorkerPlugin`. Во все обработчики вторым аргументом передаётся **logger** (всегда определён: из `options` или `console`). Специфичный для плагина конфиг задаётся при вызове **фабрики** плагина; в `options` только `logger?` и `onError?`. Параметр типа `_C` (например `PluginContext`) используется для типизации; по умолчанию контекст содержит только `logger`.
 
 ```typescript
-interface ServiceWorkerPlugin<C extends SwContext = SwContext> {
+interface ServiceWorkerPlugin<_C extends PluginContext = PluginContext> {
     name: string;
+
     order?: number;
 
-    install?: (event: ExtendableEvent, context?: C) => Promise<void> | void;
-    activate?: (event: ExtendableEvent, context?: C) => Promise<void> | void;
+    install?: (event: ExtendableEvent, logger: Logger) => Promise<void> | void;
+
+    activate?: (event: ExtendableEvent, logger: Logger) => Promise<void> | void;
+
     fetch?: (
         event: FetchEvent,
-        context?: C
+        logger: Logger
     ) => Promise<Response | undefined> | Response | undefined;
-    message?: (event: SwMessageEvent, context?: C) => void;
-    sync?: (event: SyncEvent, context?: C) => Promise<void> | void;
+
+    message?: (event: SwMessageEvent, logger: Logger) => void;
+
+    sync?: (event: SyncEvent, logger: Logger) => Promise<void> | void;
+
     push?: (
         event: PushEvent,
-        context?: C
+        logger: Logger
     ) =>
         | Promise<PushNotificationPayload | void>
         | PushNotificationPayload
         | void;
+
     periodicsync?: (
         event: PeriodicSyncEvent,
-        context?: C
+        logger: Logger
     ) => Promise<void> | void;
 }
 ```
 
-Плагин может объявить требуемый контекст через дженерик: `ServiceWorkerPlugin<SwContext & { assets: string[]; cacheName: string }>`. Тогда TypeScript потребует передать в `initServiceWorker` объект `options` с полями `assets` и `cacheName` (при вызове с литералом массива плагинов тип `options` выводится автоматически).
-
 ### 📝 Описание методов
 
-| Метод          | Событие        | Возвращает                        | Описание                                                       |
-| -------------- | -------------- | --------------------------------- | -------------------------------------------------------------- |
-| `install`      | `install`      | `void`                            | Инициализация плагина при установке SW                         |
-| `activate`     | `activate`     | `void`                            | Активация плагина при обновлении SW                            |
-| `fetch`        | `fetch`        | `Response \| undefined`           | Обработка сетевых запросов                                     |
-| `message`      | `message`      | `void`                            | Обработка сообщений от основного потока                        |
-| `sync`         | `sync`         | `void`                            | Синхронизация данных в фоне                                    |
-| `push`         | `push`         | `PushNotificationPayload \| void` | Данные для уведомления; библиотека вызывает `showNotification` |
-| `periodicsync` | `periodicsync` | `void`                            | Периодические фоновые задачи                                   |
+| Метод          | Событие        | Возвращает                                      | Описание                                    |
+| -------------- | -------------- | ----------------------------------------------- | ------------------------------------------- |
+| `install`      | `install`      | `void`                                          | Инициализация плагина при установке SW      |
+| `activate`     | `activate`     | `void`                                          | Активация плагина при обновлении SW         |
+| `fetch`        | `fetch`        | `Response \| undefined`                         | Обработка сетевых запросов                  |
+| `message`      | `message`      | `void`                                          | Обработка сообщений от основного потока     |
+| `sync`         | `sync`         | `void`                                          | Синхронизация данных в фоне                 |
+| `push`         | `push`         | `PushNotificationPayload \| false \| undefined` | Обработка и отображение сетевой нотификации |
+| `periodicsync` | `periodicsync` | `void`                                          | Периодические фоновые задачи                |
 
 ### 🎯 Особенности обработчиков
 
-- Во все методы вторым аргументом передаётся **контекст** (данные из объекта, переданного в `initServiceWorker`, без `onError`). Параметр можно не использовать, если плагину контекст не нужен.
+- Во все методы вторым аргументом передаётся **logger** (всегда определён: из `options` или `console`).
 - **`fetch`**: Возвращает `Response` для завершения цепочки или `undefined` для передачи следующему плагину. Если все плагины вернули `undefined`, фреймворк вызывает `fetch(event.request)`.
-- **`push`**: Как и fetch — возвращает `PushNotificationPayload` (объект для [Notification API](https://developer.mozilla.org/en-US/docs/Web/API/Notification)) или `undefined`. Тип экспортируется из пакета. Первый плагин, вернувший объект с `title`, «выигрывает»: библиотека вызывает `self.registration.showNotification(title, options)`. Если все вернули `undefined`, уведомление не показывается.
+- **`push`**: Возвращает `PushNotificationPayload` (объект для [Notification API](https://developer.mozilla.org/en-US/docs/Web/API/Notification)), `false` (не отображать уведомление) или `undefined` (решение об отображении отдаётся библиотеке). Вызываются все плагины с `push`. Для каждого возврата типа `PushNotificationPayload` вызывается `showNotification`. Уведомление не показывается, если все вернули `false` или смесь `undefined` и `false` без payload. Библиотека отображает одно уведомление **только когда все** плагины вернули `undefined` (и в данных есть что показывать).
 - **Остальные обработчики** (`install`, `activate`, `message`, `sync`, `periodicsync`): возвращаемое значение не используется; фреймворк вызывает метод каждого плагина по очереди, цепочка не прерывается.
 - **Все обработчики опциональны** — реализуйте только нужные события.
 
-### 🔄 Обновление Service Worker (skipWaiting / clients.claim)
-
-Библиотека **не вызывает** `skipWaiting()` и `clients.claim()` — это поведение задаётся индивидуально в каждом проекте и оставлено на усмотрение плагинов. При необходимости вызывайте их в своих обработчиках `install` и `activate` (в библиотеке реализованы данные примитивы - смотри ниже):
-
-```typescript
-const updatePlugin = {
-    name: 'update-plugin',
-    install: (event) => {
-        self.skipWaiting();
-    },
-    activate: (event) => {
-        event.waitUntil(self.clients.claim());
-    },
-};
-```
-
-## 🎯 Порядок выполнения
+## 🎯 Порядок выполнения плагинов
 
 Плагины выполняются в следующем порядке:
 
@@ -349,16 +355,16 @@ const updatePlugin = {
 ```typescript
 const plugins = [
     { name: 'first' }, // без order - выполняется первым
-    { name: 'fourth', order: 2 },
+    { name: 'fifth', order: 4 },
+    { name: 'fourth', order: 3 },
     { name: 'second' }, // без order - выполняется вторым
-    { name: 'third', order: 1 },
-    { name: 'fifth' }, // без order - выполняется третьим
+    { name: 'third', order: 2 },
 ];
 
-// Порядок выполнения: first → second → fifth → third → fourth
+// Порядок выполнения: first → second → third → fourth → fifth
 ```
 
-**Преимущества новой системы:**
+**Преимущества системы:**
 
 - 🎯 **Предсказуемость** - плагины без `order` всегда выполняются первыми
 - 🔧 **Простота** - не нужно знать, какие номера уже заняты
@@ -375,21 +381,24 @@ const plugins = [
 Все обработчики выполняются **одновременно** с помощью `Promise.all()`:
 
 ```typescript
-// Все плагины инициализируются параллельно
-const installPlugin1 = {
-    name: 'cache-assets',
-    install: async () => {
-        /* кеширование ресурсов приложения*/
-    },
-};
-const installPlugin2 = {
-    name: 'cache-ext',
-    install: async () => {
-        /* кэширование вспомогательных ресурсов */
-    },
-};
+import {
+    precache,
+    skipWaiting,
+    precacheMissing,
+} from '@budarin/pluggable-serviceworker/plugins';
 
-// Оба install обработчика выполнятся одновременно
+import { customLogger } from '../customLogger';
+import { initServiceWorker } from '@budarin/pluggable-serviceworker';
+
+// Все install-обработчики (precache, precacheMissing, skipWaiting) выполнятся параллельно
+initServiceWorker(
+    [
+        precache({ cacheName: 'app-v1', assets: ['/', '/main.js'] }),
+        precacheMissing({ cacheName: 'ext-v1', assets: ['/worker.js'] }),
+        skipWaiting,
+    ],
+    { logger: customLogger }
+);
 ```
 
 **Почему параллельно:**
@@ -403,39 +412,62 @@ const installPlugin2 = {
 
 **События:** `fetch`, `push`
 
-Обработчики выполняются **по очереди** до первого успешного результата:
+Обработчики выполняются **по очереди**:
+
+#### Fetch — с прерыванием цепочки
 
-#### Fetch - с прерыванием цепочки
+Обработчики `fetch` вызываются **по очереди**. Плагин может вернуть `Response` — тогда цепочка прерывается и этот ответ уходит клиенту. Либо вернуть `undefined` — тогда запрос передаётся следующему плагину. Если **все** плагины вернули `undefined`, фреймворк сам выполняет `fetch(event.request)`.
+
+Пример фабрики, которая прерывает цепочку при неавторизованном доступе к защищённым путям:
 
 ```typescript
-const authPlugin = {
-    name: 'auth',
-    // Без order - выполняется первым
-    fetch: async (event) => {
-        if (needsAuth(event.request)) {
-            return new Response('Unauthorized', { status: 401 }); // Прерывает цепочку
-        }
-        return undefined; // Передает следующему плагину
-    },
-};
+import type {
+    PluginContext,
+    ServiceWorkerPlugin,
+} from '@budarin/pluggable-serviceworker';
+
+function authPlugin(config: {
+    protectedPaths: string[];
+}): ServiceWorkerPlugin<PluginContext> {
+    const { protectedPaths } = config;
+
+    return {
+        name: 'auth',
+
+        fetch: async (event, logger) => {
+            const path = new URL(event.request.url).pathname;
+
+            if (protectedPaths.some((p) => path.startsWith(p))) {
+                if (needsAuth(event.request)) {
+                    logger.warn('auth: unauthorized', event.request.url);
+
+                    return new Response('Unauthorized', { status: 401 }); // Прерывает цепочку
+                }
+            }
+            return undefined; // Передаёт следующему плагину
+        },
+    };
+}
+
+// Использование: authPlugin({ protectedPaths: ['/api/'] })
 ```
 
 **Почему последовательно:**
 
-- **fetch**: Нужен только один ответ, первый успешный прерывает цепочку. Если никто не вернул ответ — выполняется `fetch(event.request)`
-- **push**: Плагин может вернуть данные для уведомления типа `PushNotificationPayload` | `undefined`. Библиотека один раз вызывает `showNotification` по первому вернувшемуся payload; цепочка прерывается — одно уведомление, без конфликтов.
+- **fetch**: Нужен только один ответ на текущий запрос браузера, первый успешный прерывает цепочку. Если никто не вернул ответ — выполняется `fetch(event.request)`
+- **push**: Плагин может вернуть `PushNotificationPayload`, `false` (не показывать) или `undefined` (решение отдаётся библиотеке). Библиотека вызывает `showNotification` для каждого payload. Не показываем, если все вернули `false` или смесь без payload. Библиотека показывает нотификацию и в случае когда **все** плагины вернули `undefined`.
 
 ### 📋 Сводная таблица
 
-| Событие        | Выполнение      | Прерывание | Причина                                                |
-| -------------- | --------------- | ---------- | ------------------------------------------------------ |
-| `install`      | Параллельно     | Нет        | Независимая инициализация                              |
-| `activate`     | Параллельно     | Нет        | Независимая активация                                  |
-| `fetch`        | Последовательно | Да         | Нужен один ответ                                       |
-| `message`      | Параллельно     | Нет        | Все получают сообщение                                 |
-| `sync`         | Параллельно     | Нет        | Независимые задачи                                     |
-| `periodicsync` | Параллельно     | Нет        | Независимые периодические задачи                       |
-| `push`         | Последовательно | Да         | Один показ уведомления (библиотека по первому payload) |
+| Событие        | Выполнение        | Прерывание | Причина                                |
+| -------------- | ----------------- | ---------- | -------------------------------------- |
+| `install`      | `Параллельно`     | `Нет`      | Независимая инициализация              |
+| `activate`     | `Параллельно`     | `Нет`      | Независимая активация                  |
+| `fetch`        | `Последовательно` | `Да`       | Нужен один ответ                       |
+| `message`      | `Параллельно`     | `Нет`      | Независимые обработчики сообщений      |
+| `sync`         | `Параллельно`     | `Нет`      | Независимые задачи                     |
+| `periodicsync` | `Параллельно`     | `Нет`      | Независимые периодические задачи       |
+| `push`         | `Последовательно` | `Нет`      | Отображение всех необходимых сообщений |
 
 ## Примитивы, пресеты и типовые сервис-воркеры
 
@@ -443,59 +475,215 @@ const authPlugin = {
 
 Один примитив — одна операция. Импорт: `@budarin/pluggable-serviceworker/plugins`.
 
-| Название                 | Событие  | Описание                                                                                                                                                                            |
-| ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **precache**             | install  | Кеширует список `context.assets` в кеш `context.cacheName`.                                                                                                                         |
-| **skipWaiting**          | install  | Вызывает `skipWaiting()`.                                                                                                                                                           |
-| **claim**                | activate | Вызывает `clients.claim()`.                                                                                                                                                         |
-| **claimOnMessage**       | message  | При сообщении с `event.data.type === context.claimMessageType` (по умолчанию `'SW_ACTIVATE'`) вызывает `skipWaiting()`. `clients.claim()` вызывается плагином **claim** в activate. |
-| **serveFromCache**       | fetch    | Отдаёт из кеша; при промахе — undefined.                                                                                                                                            |
-| **restoreAssetToCache**  | fetch    | Для URL из `context.assets`: сначала из кеша; если в кеше нет — запрос с сервера, в кеш, ответ браузеру.                                                                            |
-| **cacheFirst**           | fetch    | Кеш → при промахе сеть, ответ в кеш.                                                                                                                                                |
-| **networkFirst**         | fetch    | Сеть → при ошибке/офлайне из кеша.                                                                                                                                                  |
-| **staleWhileRevalidate** | fetch    | Отдаёт из кеша, в фоне обновляет кеш из сети.                                                                                                                                       |
+Примитивы с конфигом — **фабрики плагинов** (см. раздел «Фабрика плагинов»): конфиг передаётся при вызове по месту использования; в `options` в `initServiceWorker` попадают только `logger?` и `onError?`. Примитивы без конфига (`skipWaiting`, `claim`, …) — готовые объекты плагинов.
+
+| Название                        | Событие    | Описание                                                                                                                     |
+| ------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `precache*(config)`             | `install`  | Кеширует список ресурсов из `config.assets` в кеш `config.cacheName`.                                                        |
+| `precacheAndNotify(config)`     | `install`  | Как **precache**, затем отправляет активным клиентам сообщение `{ type: config.messageType }` (по умолчанию `SW_INSTALLED`). |
+| `precacheMissing(config)`       | `install`  | Добавляет в кеш только те ресурсы из `config.assets`, которых ещё нет в кеше.                                                |
+| `pruneStaleCache(config)`       | `activate` | Удаляет из кеша записи, чей URL не входит в `config.assets`.                                                                 |
+| `skipWaiting`                   | `install`  | Вызывает `skipWaiting()`.                                                                                                    |
+| `claim`                         | `activate` | Вызывает `clients.claim()`.                                                                                                  |
+| `reloadClients`                 | `activate` | Перезагружает все окна-клиенты через `client.navigate(client.url)`.                                                          |
+| `claimAndReloadClients`         | `activate` | Композиция **claim** + **reloadClients**: сначала claim, затем перезагрузка (порядок гарантирован — один плагин).            |
+| `skipWaitingOnMessage(config?)` | `message`  | При сообщении с `event.data.type === 'SW_MSG_SKIP_WAITING'` вызывает `skipWaiting()`.                                        |
+| `serveFromCache(config)`        | `fetch`    | Отдаёт ресурс из кеша `config.cacheName`; при отсутствии его в кэше — undefined.                                             |
+| `restoreAssetToCache(config)`   | `fetch`    | Для URL из `config.assets`: отдам ресурс из кеша или запрашиваем по сети, затем в кладем кго в кеш. Иначе — undefined.       |
+| `cacheFirst(config)`            | `fetch`    | Отдаем ресурс из кэша `config.cacheName`: при отсутствии его в кэше — делаем запрос на сервер и затем кладем ответ в кэш.    |
+| `networkFirst(config)`          | `fetch`    | Делаем запрос на сервер, при успехе — кладем его в кэш. При ошибке — отдаем из кэша. Иначе - `undefined`.                    |
+| `staleWhileRevalidate(config)`  | `fetch`    | Отдаёт из кэша, в фоне обновляет кэш.                                                                                        |
+
+#### Композиция примитивов
+
+Обработчики одного типа (`install`, `activate` и т.д.) у разных плагинов выполняются **параллельно**. Если нужна строгая последовательность (например «сначала claim, потом перезагрузка клиентов»), соберите один плагин, который по очереди вызывает логику примитивов — для гарантии порядка.
+
+**Пример: claimAndReloadClients как композиция двух примитивов**
+
+Плагин **claimAndReloadClients** вызывает существующие примитивы **claim** и **reloadClients** по очереди:
+
+```typescript
+import { claim } from '@budarin/pluggable-serviceworker/plugins';
+import { reloadClients } from '@budarin/pluggable-serviceworker/plugins';
+
+const claimPlugin = claim();
+const reloadPlugin = reloadClients();
+
+activate: (event, logger) =>
+    Promise.resolve(claimPlugin.activate(event, logger)).then(() =>
+        reloadPlugin.activate(event, logger)
+    ),
+```
+
+**Пример: кастомный кэш и логика по URL**
+
+Фабрика `postsSwrPlugin(config)` возвращает плагин, который применяет `stale-while-revalidate`(SWR) только к запросам, подходящим под `pathPattern`.
+
+```typescript
+// postsSwrPlugin.ts
+import type { Plugin } from '@budarin/pluggable-serviceworker';
 
-Контекст для кеширующих примитивов: `OfflineFirstContext` (assets, cacheName, опционально claimMessageType). Импортируйте тип из основного пакета.
+import {
+    precache,
+    serveFromCache,
+} from '@budarin/pluggable-serviceworker/plugins';
+import { initServiceWorker } from '@budarin/pluggable-serviceworker';
+
+function postsSwrPlugin(config: {
+    cacheName: string;
+    pathPattern?: RegExp;
+}): Plugin {
+    const { cacheName, pathPattern = /\/api\/posts(\/|$)/ } = config;
+
+    return {
+        name: 'postsSwr',
+        order: 0,
+
+        fetch: async (event) => {
+            if (!pathPattern.test(new URL(event.request.url).pathname)) {
+                return undefined;
+            }
+
+            const cache = await caches.open(cacheName);
+            const cached = await cache.match(event.request);
+            const revalidate = fetch(event.request).then(async (response) => {
+                if (response.ok) {
+                    await cache.put(event.request, response.clone());
+                }
+
+                return response;
+            });
+
+            if (cached) {
+                void revalidate;
+                return cached;
+            }
+
+            return revalidate;
+        },
+    };
+}
+```
+
+```typescript
+// sw.ts
+const staticCache = 'static-v1';
+const assets = ['/', '/main.js'];
+
+initServiceWorker(
+    [
+        precache({ cacheName: staticCache, assets }),
+        serveFromCache({ cacheName: staticCache }),
+        postsSwrPlugin({ cacheName: 'posts' }),
+    ],
+    { logger: console }
+);
+```
 
 ### Пресеты
 
 Комбинации примитивов (стратегии кеширования). Импорт: `@budarin/pluggable-serviceworker/presets`.
 
-| Название         | Состав                    | Назначение                           |
-| ---------------- | ------------------------- | ------------------------------------ |
-| **offlineFirst** | precache + serveFromCache | Статика из кеша, при промахе — сеть. |
+| Название               | Состав                                      | Назначение                                                                |
+| ---------------------- | ------------------------------------------- | ------------------------------------------------------------------------- |
+| `offlineFirst(config)` | `precache(config) + serveFromCache(config)` | Статика из кеша, при отсутствии ресурса в кэше — делаем запрос к серверу. |
 
+Конфиг пресета: `OfflineFirstConfig` (cacheName, assets). Импорт из `@budarin/pluggable-serviceworker/presets`.
 Стратегии **networkFirst**, **staleWhileRevalidate** и др. доступны как примитивы — собирайте свой кастомный сервис-воркер из примитивов и пресетов.
 
 ### Типовые сервис-воркеры (из коробки)
 
 Готовые точки входа по **моменту активации** (все с кешированием offline-first). Импорт: `@budarin/pluggable-serviceworker/sw`.
 
-| Название                             | Описание                                                                                            |
-| ------------------------------------ | --------------------------------------------------------------------------------------------------- |
-| **activateOnNextVisitServiceWorker** | Кеширующий SW, активируется при следующем визите страницы.                                          |
-| **activateImmediatelyServiceWorker** | Кеширующий SW, активируется сразу (skipWaiting + claim).                                            |
-| **activateOnSignalServiceWorker**    | Кеширующий SW, активируется по сигналу со страницы (сообщение с типом из options.claimMessageType). |
+| Название                           | Описание                                                                                                                              |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `activateOnNextVisitServiceWorker` | Кеширующий SW, активируется и обновляется при следующем визите на страницу (перезагрузке) после загрузки нового сервисворкера.        |
+| `activateImmediatelyServiceWorker` | Кеширующий SW, активируется и вступает в действие сразу при 1-й загрузке и при обновлении.                                            |
+| `activateOnSignalServiceWorker`    | Кеширующий SW, устанавливается сразу, но активируется при обновлении только по сигналу со страницы (сообщение `SW_MSG_SKIP_WAITING`). |
 
 Пример использования типового SW:
 
 ```typescript
 // sw.js — точка входа вашего сервис-воркера
+import { customLogger } from './customLogger';
 import { activateOnNextVisitServiceWorker } from '@budarin/pluggable-serviceworker/sw';
 
 activateOnNextVisitServiceWorker({
     assets: ['/', '/styles.css', '/script.js'],
     cacheName: 'my-cache-v1',
-    logger: console,
-    onError: (err, event, type) => console.error(type, err),
+    logger: customLogger,
+    onError: (err, event, type) => customLogger.error(type, err),
 });
 ```
 
 На странице регистрируйте этот файл: `navigator.serviceWorker.register('/sw.js')` (или путь, по которому сборка отдаёт ваш sw.js).
 
+### Публикуемые утилиты
+
+Утилиты, доступные для использования в своих плагинах. Импорт: `@budarin/pluggable-serviceworker/utils`.
+
+| Название                     | Описание                                                                 |
+| ---------------------------- | ------------------------------------------------------------------------ |
+| `normalizeUrl(url)`          | Нормализует URL (относительный → абсолютный по origin SW) для сравнения. |
+| `notifyClients(messageType)` | Отправляет сообщение `{ type: messageType }` всем окнам-клиентам (SW).   |
+
+## Разработка пакета плагина
+
+Типы для описания плагина экспортируются из этого пакета. Отдельный пакет с плагином не публикует свои типы — он объявляет зависимость от `@budarin/pluggable-serviceworker` и импортирует типы оттуда.
+
+**1. Зависимости в пакете плагина**
+
+В `package.json` своего пакета добавьте:
+
+```json
+{
+    "peerDependencies": {
+        "@budarin/pluggable-serviceworker": "^1.0.0"
+    },
+    "devDependencies": {
+        "@budarin/pluggable-serviceworker": "^1.5.0"
+    }
+}
+```
+
+`peerDependencies` — чтобы плагин работал с той версией библиотеки, которую установил пользователь; в `devDependencies` — для сборки и типов.
+
+**2. Импорт типов в коде плагина**
+
+Импортируйте тип **`Plugin`** (алиас для `ServiceWorkerPlugin<PluginContext>`); при необходимости — `Logger`, `SwMessageEvent`, `PushNotificationPayload` и др.
+
+```typescript
+import type { Plugin } from '@budarin/pluggable-serviceworker';
+
+export interface MyPluginConfig {
+    cacheName: string;
+}
+
+export function myPlugin(config: MyPluginConfig): Plugin {
+    const { cacheName } = config;
+
+    return {
+        name: 'my-plugin',
+
+        install: async (_event, logger) => {
+            logger.info('my-plugin: install');
+            const cache = await caches.open(cacheName);
+            await cache.add('/offline.html');
+        },
+
+        fetch: async (event, _logger) => {
+            const cached = await caches.match(event.request);
+            return cached ?? undefined;
+        },
+    };
+}
+```
+
+Пользователь подключает плагин так: `initServiceWorker([..., myPlugin({ cacheName: 'my-v1' })], options)`.
+
 ## Режим разработки
 
-Если нужно, чтобы в режиме разработки ни один из плагинов ничего не кэшировал и не пытался что-либо отдавать из кэша - в плагине и сервисворкере можно использовть `import.meta.env.DEV` для Vite для условного использования кэширования.
+В режиме разработки - используйте `import.meta.env.DEV` для Vite для условного использования кода.
 
 ## 📄 Лицензия