decoy-duck 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitry Tomin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,180 @@
-# Temporary Holding Version
+# decoy-duck
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Проверка фильтра рекламы в браузере. Четыре пробы сводятся в вердикт с уровнем уверенности.
+
+Фильтр смотрит на URL запроса. Четыре файла-приманки лежат на сайте как обычная статика и запрашиваются браузером по известным путям. В бандл приложения они не входят.
+
+## Установка
+
+```
+npm install decoy-duck
+```
+
+Пакет публичный, отдельный registry не нужен.
+
+## Подключение
+
+Два шага: вызвать проверку и положить файлы-приманки в корень сайта.
+
+```js
+import { detectAdblock } from 'decoy-duck'
+
+const result = await detectAdblock()
+```
+
+Скопируйте файлы из `node_modules/decoy-duck/src/filter-check/baits/` в выходной каталог сборки. Имена остаются такими:
+
+| Файл в пакете | Адрес на сайте |
+|---|---|
+| `ad_header.js` | `/ad_header.js` |
+| `assets/ctrl.js` | `/assets/ctrl.js` |
+| `assets/pixel.png` | `/assets/pixel.png` |
+| `ads/images/pixel.png` | `/ads/images/pixel.png` |
+
+Хеш в имени файла меняет URL, и правило фильтра его уже не узнает.
+
+В Webpack это делает `copy-webpack-plugin`:
+
+```js
+import CopyPlugin from 'copy-webpack-plugin'
+
+export default {
+  plugins: [
+    new CopyPlugin({
+      patterns: [
+        { from: 'node_modules/decoy-duck/src/filter-check/baits/ad_header.js', to: 'ad_header.js' },
+        { from: 'node_modules/decoy-duck/src/filter-check/baits/assets/ctrl.js', to: 'assets/ctrl.js' },
+        { from: 'node_modules/decoy-duck/src/filter-check/baits/assets/pixel.png', to: 'assets/pixel.png' },
+        { from: 'node_modules/decoy-duck/src/filter-check/baits/ads/images/pixel.png', to: 'ads/images/pixel.png' },
+      ],
+    }),
+  ],
+}
+```
+
+Эти четыре файла оставляют статикой. Импорт их в свой модуль затягивает содержимое в бандл: браузер не делает запрос по нужному URL, и фильтр ничего не видит.
+
+Сайт из корня домена дополнительных адресов не требует. Если страница открывается из `/app/`, файлы лежат по `/app/ad_header.js` и остальным трём путям, а проверка получает эти адреса явно:
+
+```js
+import { detectAdblock, defaultBait } from 'decoy-duck'
+
+const result = await detectAdblock({
+  bait: {
+    ...defaultBait,
+    scriptUrl: '/app/ad_header.js',
+    imageUrl: '/app/ads/images/pixel.png',
+    controlScriptUrl: '/app/assets/ctrl.js',
+    controlImageUrl: '/app/assets/pixel.png',
+  },
+})
+```
+
+Без плагина путь с ведущим `/` уходит как написан в `bait`. Плагин Vite сам добавляет к такому пути `base`. Абсолютный `https://` в обоих случаях передаётся как есть.
+
+## Результат
+
+`detected` равен `true`, только если статус `active`. `false` — фильтр не найден. `null` — часть проб не ответила, вывода нет.
+
+```js
+{
+  detected: true,
+  status: 'active',      // active | inactive | unknown
+  confidence: 'high',    // high | medium | low
+  probability: 90,       // 0–100, вероятность что фильтр включён
+  signals: {
+    cosmetic: 'clear',   // blocked | clear | inconclusive
+    script: 'blocked',
+    image: 'clear',
+    thirdParty: 'clear', // blocked | clear | inconclusive | skipped
+  },
+  elapsedMs: 1040,
+}
+```
+
+Четыре пробы стартуют параллельно. У скрипта и картинки есть нейтральный контроль. Если не открылся и он, проба остаётся `inconclusive`.
+
+- Заблокированный скрипт или картинка на своём домене — `active`, уверенность высокая.
+- Вместе скрытый элемент и недоступный сторонний рекламный хост — `active`, уверенность высокая.
+- Только скрытый элемент — `active`, уверенность средняя.
+- Только сторонний хост, а остальные пробы открылись — `active`, уверенность средняя. Это «рекламный хост недоступен»: фильтр, прокси, DNS или сам хост.
+- Все свои пробы открылись, а сторонняя выключена (`skipped`) или тоже открылась — `inactive`, уверенность высокая.
+- Иначе — `unknown`.
+
+`probability` — вероятность, что фильтр включён, от 0 до 100:
+
+- оба своих файла закрыты — 98
+- закрыт один из них — 90
+- скрыт элемент и недоступен сторонний хост — 85
+- скрыт только элемент — 60
+- недоступен только сторонний хост — 40
+- свои пробы открылись — 5
+- вывода нет — 50
+
+`decide(signals)` — чистая функция того же правила. Типы лежат рядом с входом пакета.
+
+## Опции
+
+```js
+import { detectAdblock, defaultBait } from 'decoy-duck'
+
+const controller = new AbortController()
+
+const result = await detectAdblock({
+  timeout: 2500,
+  signal: controller.signal,
+  thirdParty: false,
+  bait: { ...defaultBait },
+})
+```
+
+`timeout` — предел сетевых проб в миллисекундах, по умолчанию 2500. `signal` отменяет проверку.
+
+`thirdParty: false` не отправляет запрос к рекламному хосту. По умолчанию проверка один раз запрашивает `pagead2.googlesyndication.com`. Cookies и referrer не уходят, но хост видит IP и User-Agent. Скрипт Google при этом не выполняется.
+
+Обрыв этого запроса — не доказательство фильтра. Так же выглядят CSP, корпоративный прокси, сбой DNS и недоступность самого хоста. Поэтому одна только сторонняя проба даёт `active` со средней уверенностью. Высокую уверенность дают заблокированные скрипт или картинка на своём домене.
+
+## Vite
+
+В проекте на Vite те же четыре файла может разложить плагин. Это необязательный путь: проверка по-прежнему вызывается через `detectAdblock()`.
+
+```js
+import { defineConfig } from 'vite'
+import { filterCheck } from 'decoy-duck/vite'
+
+export default defineConfig({
+  plugins: [filterCheck()],
+})
+```
+
+Плагин в dev отдаёт файлы по адресам из `defaultBait` с учётом Vite `base` и при `vite build` копирует их в `build.outDir`. Этот каталог считается от `root` конфига, а не от текущей папки процесса. Файлы остаются в корне выходного каталога: `base` — это префикс URL, а не вложенная папка. Свои пути с ведущим `/` в `bait` получают этот префикс сами.
+
+Импорт пакета в dev собирается в виртуальный модуль с нейтральным id: иначе Vite запросил бы файл из `node_modules/decoy-duck/`, и блокировщик мог бы вырезать сам детектор.
+
+Если файл с тем же путём уже лежит в выходном каталоге и байты отличаются, сборка останавливается и не затирает его.
+
+## Разработка этого репозитория
+
+Проверка без браузера: `npm test`.
+
+Браузерный прогон с живыми расширениями: `npm run test:browser`. Окно при этом не открывается. Чтобы смотреть демо на экране, по одному расширению за раз: `HEADED=1 npm run test:browser`. Он не входит в `npm test` и перед публикацией не запускается. Chromium качает Playwright, сборки расширений — скрипт, в `.cache/extensions`. Страница открывается как `localtest.me`, а не `localhost`: списки фильтров не трогают локальный хост.
+
+Сейчас в прогоне чистый Chromium, uBlock Origin Lite (оптимальный и полный режим), AdGuard, [Adblock Plus](https://adblockplus.org/ru/) и Ghostery. Полный uBlock Origin в текущем релизе всё ещё Manifest V2, Chromium его не загружает.
+
+`npm run dev` в этом репозитории открывает демо через тот же публичный вход и плагин Vite.
+
+## Публикация
+
+Пакет публичный, без scope. Репозиторий: `github.com/N3P0m/decoy-duck`. Следующие версии отправляет GitHub Actions по тегу `v*`, файл `.github/workflows/publish.yml`. Версия в теге должна совпасть с `version` в `package.json`. Перед отправкой `prepublishOnly` запускает тесты.
+
+Первый выпуск имени, которого ещё нет в реестре, делается локально: `npm login`, затем `npm publish`. npm спросит код 2FA. Trusted Publishing настраивается только у уже существующего пакета, поэтому секрет `NPM_TOKEN` workflow не использует.
+
+Сразу после появления пакета на npmjs.com откройте его → Settings → Trusted Publisher → GitHub Actions:
+
+- Organization or user: `N3P0m`
+- Repository: `decoy-duck`
+- Workflow filename: `publish.yml`
+- Environment оставьте пустым
+- Разрешите прямую публикацию через `npm publish`. Новые настройки по умолчанию пускают только `npm stage publish`.
+
+Первая успешная публикация через этот publisher должна пройти в течение 48 часов, иначе настройка сгорает. Поле `repository.url` в `package.json` должно остаться `git+https://github.com/N3P0m/decoy-duck.git`: npm сверяет его с репозиторием, из которого пришёл OIDC-токен. Репозиторий должен быть публичным, иначе provenance не появится.

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "decoy-duck",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Проверка фильтра рекламы в браузере: четыре пробы и вероятность, что фильтр включён. Для Vite есть плагин, который отдаёт bait-файлы.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/N3P0m/decoy-duck.git"
+  },
+  "homepage": "https://github.com/N3P0m/decoy-duck#readme",
+  "bugs": {
+    "url": "https://github.com/N3P0m/decoy-duck/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/filter-check/index.d.ts",
+      "default": "./src/filter-check/index.js"
+    },
+    "./vite": {
+      "types": "./src/filter-check/vite.d.ts",
+      "default": "./src/filter-check/vite.js"
+    }
+  },
+  "types": "./src/filter-check/index.d.ts",
+  "files": [
+    "src/filter-check",
+    "README.md",
+    "!src/filter-check/**/*.test.js"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "node --test test/*.test.js && tsc --noEmit -p tsconfig.json",
+    "test:browser": "node --test --test-timeout 300000 test/browser/extensions.test.js",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "esbuild": "^0.28.2"
+  },
+  "devDependencies": {
+    "playwright": "^1.56.1",
+    "typescript": "^5.9.3",
+    "vite": "^8.3.4"
+  }
+}

package/src/filter-check/baits/ad_header.js

@@ -0,0 +1,10 @@
+(function () {
+  try {
+    var src = document.currentScript && document.currentScript.src;
+    if (!src) return;
+    var token = new URL(src).searchParams.get('t');
+    if (!token) return;
+    var bag = globalThis.__hdrBag || (globalThis.__hdrBag = Object.create(null));
+    bag[token] = 1;
+  } catch (e) {}
+})();

package/src/filter-check/baits/assets/ctrl.js

@@ -0,0 +1,10 @@
+(function () {
+  try {
+    var src = document.currentScript && document.currentScript.src;
+    if (!src) return;
+    var token = new URL(src).searchParams.get('t');
+    if (!token) return;
+    var bag = globalThis.__ctlBag || (globalThis.__ctlBag = Object.create(null));
+    bag[token] = 1;
+  } catch (e) {}
+})();

package/src/filter-check/detect.js

@@ -0,0 +1,130 @@
+import { decide } from './verdict.js';
+import { probeCosmetic } from './probes/cosmetic.js';
+import { probeImagePair, probeScriptPair, probeThirdParty } from './probes/resource.js';
+import { applyBase, publicBase } from './urls.js';
+
+const DEFAULT_TIMEOUT = 2500;
+
+/** Адреса проб. Файлы из `baits/` должны отдаваться по этим путям как статика. */
+export const defaultBait = {
+  scriptUrl: '/ad_header.js',
+  imageUrl: '/ads/images/pixel.png',
+  controlScriptUrl: '/assets/ctrl.js',
+  controlImageUrl: '/assets/pixel.png',
+  thirdPartyUrl: 'https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js',
+};
+
+function domReady(signal) {
+  if (signal?.aborted) return Promise.resolve(false);
+  if (document.readyState !== 'loading') return Promise.resolve(true);
+  return new Promise((resolve) => {
+    const onReady = () => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve(true);
+    };
+    const onAbort = () => {
+      document.removeEventListener('DOMContentLoaded', onReady);
+      resolve(false);
+    };
+    document.addEventListener('DOMContentLoaded', onReady, { once: true });
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+function blank() {
+  return {
+    detected: null,
+    status: 'unknown',
+    confidence: 'low',
+    probability: 50,
+    signals: {
+      cosmetic: 'inconclusive',
+      script: 'inconclusive',
+      image: 'inconclusive',
+      thirdParty: 'inconclusive',
+    },
+    elapsedMs: 0,
+  };
+}
+
+/**
+ * Проверяет, режет ли страница рекламу.
+ * Сетевые bait-файлы не входят в бандл: их URL должны совпасть с правилами фильтра.
+ *
+ * @param {object} [options]
+ * @param {number} [options.timeout=2500] Таймаут сетевых проб, мс.
+ * @param {AbortSignal} [options.signal] Отмена проверки.
+ * @param {Partial<typeof defaultBait>} [options.bait] Свои URL вместо `defaultBait`.
+ * @param {boolean} [options.thirdParty=true] Запрос к рекламному хосту. `false` его не отправляет.
+ * @returns {Promise<{
+ *   detected: boolean | null,
+ *   status: 'active' | 'inactive' | 'unknown',
+ *   confidence: 'high' | 'medium' | 'low',
+ *   probability: number,
+ *   signals: {
+ *     cosmetic: 'blocked' | 'clear' | 'inconclusive',
+ *     script: 'blocked' | 'clear' | 'inconclusive',
+ *     image: 'blocked' | 'clear' | 'inconclusive',
+ *     thirdParty: 'blocked' | 'clear' | 'inconclusive' | 'skipped',
+ *   },
+ *   elapsedMs: number,
+ * }>} `detected === true` только при `status: 'active'`. `null` значит, что ответа нет.
+ */
+function withBase(bait, base) {
+  return {
+    ...bait,
+    scriptUrl: applyBase(base, bait.scriptUrl),
+    imageUrl: applyBase(base, bait.imageUrl),
+    controlScriptUrl: applyBase(base, bait.controlScriptUrl),
+    controlImageUrl: applyBase(base, bait.controlImageUrl),
+  };
+}
+
+export async function detectAdblock(options = {}) {
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+  const bait = withBase({ ...defaultBait, ...options.bait }, publicBase());
+  const signal = options.signal;
+  const thirdPartyEnabled = options.thirdParty !== false && Boolean(bait.thirdPartyUrl);
+
+  const ready = await domReady(signal);
+  if (!ready || signal?.aborted) return blank();
+
+  const started = performance.now();
+  const [cosmetic, script, image, thirdParty] = await Promise.all([
+    probeCosmetic({ signal }).catch(() => ({ status: 'inconclusive', control: 'error' })),
+    probeScriptPair({
+      controlUrl: bait.controlScriptUrl,
+      baitUrl: bait.scriptUrl,
+      timeout,
+      signal,
+    }).catch(() => ({ status: 'inconclusive', control: 'error' })),
+    probeImagePair({
+      controlUrl: bait.controlImageUrl,
+      baitUrl: bait.imageUrl,
+      timeout,
+      signal,
+    }).catch(() => ({ status: 'inconclusive', control: 'error' })),
+    thirdPartyEnabled
+      ? probeThirdParty({ url: bait.thirdPartyUrl, timeout, signal }).catch(() => 'failed')
+      : Promise.resolve('skipped'),
+  ]);
+
+  const controlOk = script.control === 'loaded' || image.control === 'loaded';
+  let thirdPartyStatus = 'inconclusive';
+  if (thirdParty === 'skipped') thirdPartyStatus = 'skipped';
+  else if (thirdParty === 'ok') thirdPartyStatus = 'clear';
+  else if (thirdParty === 'failed' && controlOk) thirdPartyStatus = 'blocked';
+
+  const signals = {
+    cosmetic: cosmetic.status,
+    script: script.status,
+    image: image.status,
+    thirdParty: thirdPartyStatus,
+  };
+
+  return {
+    ...decide(signals),
+    signals,
+    elapsedMs: Math.round(performance.now() - started),
+  };
+}

package/src/filter-check/index.d.ts

@@ -0,0 +1,51 @@
+export type ProbeStatus = 'blocked' | 'clear' | 'inconclusive' | 'skipped';
+export type DetectStatus = 'active' | 'inactive' | 'unknown';
+export type Confidence = 'high' | 'medium' | 'low';
+
+export interface BaitUrls {
+  scriptUrl: string;
+  imageUrl: string;
+  controlScriptUrl: string;
+  controlImageUrl: string;
+  thirdPartyUrl: string;
+}
+
+export interface DetectSignals {
+  cosmetic: ProbeStatus;
+  script: ProbeStatus;
+  image: ProbeStatus;
+  thirdParty: ProbeStatus;
+}
+
+export interface DetectResult {
+  detected: boolean | null;
+  status: DetectStatus;
+  confidence: Confidence;
+  /** Вероятность, что фильтр включён, от 0 до 100. */
+  probability: number;
+  signals: DetectSignals;
+  elapsedMs: number;
+}
+
+export interface DetectOptions {
+  /** Таймаут сетевых проб, мс. По умолчанию 2500. */
+  timeout?: number;
+  /** Отмена проверки. */
+  signal?: AbortSignal;
+  /** Свои URL вместо `defaultBait`. Путь с `/` уходит как написан. Префикс Vite `base` добавляет только плагин `filterCheck`. */
+  bait?: Partial<BaitUrls>;
+  /**
+   * Запрос к стороннему рекламному хосту.
+   * По умолчанию включён. `false` не отправляет его: хост узнаёт IP и User-Agent,
+   * а обрыв запроса бывает и без фильтра.
+   */
+  thirdParty?: boolean;
+}
+
+export declare const defaultBait: BaitUrls;
+
+export declare function detectAdblock(options?: DetectOptions): Promise<DetectResult>;
+
+export declare function decide(
+  signals: Partial<DetectSignals>,
+): Pick<DetectResult, 'detected' | 'status' | 'confidence' | 'probability'>;

package/src/filter-check/index.js

@@ -0,0 +1,10 @@
+/**
+ * Проверка фильтра рекламы.
+ *
+ * Файлы-приманки должны запрашиваться браузером по своим URL, их нельзя класть в бандл.
+ * Путь с ведущим `/` уходит как написан. Префикс Vite `base` добавляет только `filterCheck` из `decoy-duck/vite`.
+ * Установка описана в корневом README пакета.
+ */
+
+export { defaultBait, detectAdblock } from './detect.js';
+export { decide } from './verdict.js';

package/src/filter-check/probes/cosmetic.js

@@ -0,0 +1,76 @@
+const BAIT_CLASS = 'square-ad sticky-ad sponsored-ad static-ad';
+const CHECK_DELAYS = [100, 400];
+const SETTLE_DELAY = 1000;
+
+function isCollapsed(el) {
+  if (!el.isConnected) return true;
+  if (el.offsetHeight === 0 || el.offsetWidth === 0) return true;
+
+  const style = getComputedStyle(el);
+  if (style.display === 'none') return true;
+  if (style.visibility === 'hidden' || style.visibility === 'collapse') return true;
+  if (el.getClientRects().length === 0) return true;
+
+  return false;
+}
+
+export function probeCosmetic({ signal } = {}) {
+  return new Promise((resolve) => {
+    if (signal?.aborted || !document.body) {
+      resolve({ status: 'inconclusive' });
+      return;
+    }
+
+    const el = document.createElement('div');
+    el.className = BAIT_CLASS;
+    el.setAttribute('aria-hidden', 'true');
+    el.style.cssText = 'position:absolute;left:-9999px;top:-9999px;width:10px;height:10px;pointer-events:none;';
+    document.body.appendChild(el);
+
+    let settled = false;
+    const timers = [];
+    const observer = new MutationObserver(() => {
+      if (isCollapsed(el)) finish('blocked');
+    });
+
+    const finish = (status) => {
+      if (settled) return;
+      settled = true;
+      for (const id of timers) clearTimeout(id);
+      observer.disconnect();
+      signal?.removeEventListener('abort', onAbort);
+      el.remove();
+      resolve({ status });
+    };
+
+    const onAbort = () => finish('inconclusive');
+
+    const check = () => {
+      if (isCollapsed(el)) finish('blocked');
+    };
+
+    signal?.addEventListener('abort', onAbort, { once: true });
+    observer.observe(el, { attributes: true });
+    observer.observe(document.body, { childList: true });
+
+    check();
+    if (settled) return;
+
+    requestAnimationFrame(() => {
+      if (settled) return;
+      requestAnimationFrame(() => {
+        if (!settled) check();
+      });
+    });
+
+    for (const delay of CHECK_DELAYS) {
+      timers.push(setTimeout(check, delay));
+    }
+
+    timers.push(setTimeout(() => {
+      if (settled) return;
+      if (isCollapsed(el)) finish('blocked');
+      else finish('clear');
+    }, SETTLE_DELAY));
+  });
+}

package/src/filter-check/probes/resource.js

@@ -0,0 +1,151 @@
+const CONTROL_FLAG = '__ctl';
+const BAIT_FLAG = '__hdr';
+
+function withCacheBust(url) {
+  const glue = url.includes('?') ? '&' : '?';
+  return `${url}${glue}t=${Date.now()}`;
+}
+
+function loadScript(url, flag, timeout, signal) {
+  return new Promise((resolve) => {
+    if (signal?.aborted || !document.head) {
+      resolve('aborted');
+      return;
+    }
+
+    const script = document.createElement('script');
+    let settled = false;
+    const timer = setTimeout(() => finish('timeout'), timeout);
+
+    const token = `${Date.now().toString(36)}${Math.random().toString(36).slice(2)}`;
+    const glue = url.includes('?') ? '&' : '?';
+    const bag = `${flag}Bag`;
+
+    const dropToken = () => {
+      const store = globalThis[bag];
+      if (!store) return;
+      delete store[token];
+      if (Object.keys(store).length === 0) delete globalThis[bag];
+    };
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+      script.onload = null;
+      script.onerror = null;
+      script.remove();
+      dropToken();
+      resolve(result);
+    };
+
+    const onAbort = () => finish('aborted');
+    script.onload = () => finish(globalThis[bag]?.[token] === 1 ? 'loaded' : 'empty');
+    script.onerror = () => finish('error');
+    script.async = true;
+    script.src = `${url}${glue}t=${token}`;
+    signal?.addEventListener('abort', onAbort, { once: true });
+    document.head.appendChild(script);
+  });
+}
+
+function loadImage(url, timeout, signal) {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve('aborted');
+      return;
+    }
+
+    const img = new Image();
+    let settled = false;
+    const timer = setTimeout(() => finish('timeout'), timeout);
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+      img.onload = null;
+      img.onerror = null;
+      resolve(result);
+    };
+
+    const onAbort = () => finish('aborted');
+
+    img.onload = () => finish(img.naturalWidth > 0 ? 'loaded' : 'empty');
+    img.onerror = () => finish('error');
+    signal?.addEventListener('abort', onAbort, { once: true });
+    img.src = withCacheBust(url);
+  });
+}
+
+export function interpretPair(control, bait) {
+  if (control === 'loaded' && (bait === 'error' || bait === 'timeout' || bait === 'empty')) {
+    return 'blocked';
+  }
+  if (control === 'loaded' && bait === 'loaded') return 'clear';
+  return 'inconclusive';
+}
+
+export function probeScriptPair({ controlUrl, baitUrl, timeout, signal }) {
+  return Promise.all([
+    loadScript(controlUrl, CONTROL_FLAG, timeout, signal),
+    loadScript(baitUrl, BAIT_FLAG, timeout, signal),
+  ]).then(([control, bait]) => ({
+    status: interpretPair(control, bait),
+    control,
+    bait,
+  }));
+}
+
+export function probeImagePair({ controlUrl, baitUrl, timeout, signal }) {
+  return Promise.all([
+    loadImage(controlUrl, timeout, signal),
+    loadImage(baitUrl, timeout, signal),
+  ]).then(([control, bait]) => ({
+    status: interpretPair(control, bait),
+    control,
+    bait,
+  }));
+}
+
+export function probeThirdParty({ url, timeout, signal }) {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve('aborted');
+      return;
+    }
+
+    const controller = new AbortController();
+    let aborted = false;
+    const timer = setTimeout(() => controller.abort(), timeout);
+
+    const onAbort = () => {
+      aborted = true;
+      controller.abort();
+    };
+
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+      resolve(result);
+    };
+
+    signal?.addEventListener('abort', onAbort, { once: true });
+
+    fetch(url, {
+      mode: 'no-cors',
+      cache: 'no-store',
+      credentials: 'omit',
+      referrerPolicy: 'no-referrer',
+      signal: controller.signal,
+    }).then(
+      () => finish('ok'),
+      () => finish(aborted || signal?.aborted ? 'aborted' : 'failed'),
+    );
+  });
+}

package/src/filter-check/urls.js

@@ -0,0 +1,34 @@
+export const BAIT_FILES = {
+  '/ad_header.js': 'ad_header.js',
+  '/assets/ctrl.js': 'assets/ctrl.js',
+  '/assets/pixel.png': 'assets/pixel.png',
+  '/ads/images/pixel.png': 'ads/images/pixel.png',
+};
+
+export function applyBase(base, url) {
+  if (!url.startsWith('/') || url.startsWith('//')) return url;
+  if (!base || base === '/') return url;
+  const prefix = base.endsWith('/') ? base.slice(0, -1) : base;
+  return `${prefix}${url}`;
+}
+
+export function publicBase() {
+  if (typeof __filterCheckBase === 'string' && __filterCheckBase) return __filterCheckBase;
+  const env = import.meta.env;
+  if (!env) return '/';
+  const base = env.BASE_URL;
+  return typeof base === 'string' && base.length > 0 ? base : '/';
+}
+
+export function stripBase(pathname, base) {
+  if (!base || base === '/' || base === './') return pathname;
+  const prefix = base.endsWith('/') ? base.slice(0, -1) : base;
+  if (pathname === prefix) return '/';
+  if (pathname.startsWith(`${prefix}/`)) return pathname.slice(prefix.length);
+  return pathname;
+}
+
+export function matchBait(url = '', base = '/') {
+  const pathname = stripBase(url.split('?')[0], base);
+  return BAIT_FILES[pathname] ?? null;
+}

package/src/filter-check/verdict.js

@@ -0,0 +1,60 @@
+const KNOWN = new Set(['blocked', 'clear', 'inconclusive', 'skipped']);
+
+function read(signals, key) {
+  const value = signals?.[key];
+  return KNOWN.has(value) ? value : 'inconclusive';
+}
+
+/**
+ * Сводит четыре статуса проб в вердикт. Чистая функция, без DOM.
+ *
+ * @param {{ cosmetic?: string, script?: string, image?: string, thirdParty?: string }} signals
+ *   Каждый статус: `blocked`, `clear` или `inconclusive`.
+ * @returns {{
+ *   detected: boolean | null,
+ *   status: 'active' | 'inactive' | 'unknown',
+ *   confidence: 'high' | 'medium' | 'low',
+ *   probability: number,
+ * }} `probability` — вероятность, что фильтр включён, от 0 до 100.
+ */
+export function decide(signals) {
+  const cosmetic = read(signals, 'cosmetic');
+  const script = read(signals, 'script');
+  const image = read(signals, 'image');
+  const thirdParty = read(signals, 'thirdParty');
+
+  if (script === 'blocked' || image === 'blocked') {
+    const both = script === 'blocked' && image === 'blocked';
+    return { detected: true, status: 'active', confidence: 'high', probability: both ? 98 : 90 };
+  }
+
+  if (cosmetic === 'blocked' && thirdParty === 'blocked') {
+    return { detected: true, status: 'active', confidence: 'high', probability: 85 };
+  }
+
+  if (cosmetic === 'blocked') {
+    return { detected: true, status: 'active', confidence: 'medium', probability: 60 };
+  }
+
+  if (
+    thirdParty === 'blocked' &&
+    cosmetic === 'clear' &&
+    script === 'clear' &&
+    image === 'clear'
+  ) {
+    return { detected: true, status: 'active', confidence: 'medium', probability: 40 };
+  }
+
+  const thirdPartyClear = thirdParty === 'clear' || thirdParty === 'skipped';
+
+  if (
+    cosmetic === 'clear' &&
+    script === 'clear' &&
+    image === 'clear' &&
+    thirdPartyClear
+  ) {
+    return { detected: false, status: 'inactive', confidence: 'high', probability: 5 };
+  }
+
+  return { detected: null, status: 'unknown', confidence: 'low', probability: 50 };
+}

package/src/filter-check/vite.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from 'vite';
+
+/** Отдаёт bait-файлы в dev и копирует их в `outDir` при сборке. `outDir` считается от `config.root`, URL — от `config.base`. */
+export declare function filterCheck(): Plugin;

package/src/filter-check/vite.js

@@ -0,0 +1,103 @@
+import { build } from 'esbuild';
+import { cpSync, createReadStream, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, extname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { BAIT_FILES, matchBait } from './urls.js';
+
+const root = dirname(fileURLToPath(import.meta.url));
+const entry = join(root, 'index.js');
+const baits = join(root, 'baits');
+const VIRTUAL = '\0filter-check';
+const PACKAGE = 'decoy-duck';
+
+const TYPES = {
+  '.js': 'text/javascript; charset=utf-8',
+  '.png': 'image/png',
+};
+
+export function resolveOutDir(projectRoot, outDir) {
+  return isAbsolute(outDir) ? outDir : resolve(projectRoot, outDir);
+}
+
+function serveBaits(base, req, res, next) {
+  const rel = matchBait(req.url, base);
+  if (!rel) {
+    next();
+    return;
+  }
+
+  const file = join(baits, rel);
+  if (!existsSync(file)) {
+    next();
+    return;
+  }
+
+  res.setHeader('Content-Type', TYPES[extname(file)] || 'application/octet-stream');
+  res.setHeader('Cache-Control', 'no-store');
+  createReadStream(file).pipe(res);
+}
+
+export function copyBaits(targetDir) {
+  for (const rel of Object.values(BAIT_FILES)) {
+    const source = join(baits, rel);
+    const dest = join(targetDir, rel);
+    if (existsSync(dest)) {
+      const same = readFileSync(source).equals(readFileSync(dest));
+      if (!same) {
+        throw new Error(
+          `filter-check: ${dest} уже есть и отличается от bait-файла пакета. Переименуйте свой файл, иначе проверка рекламы получит не тот ответ.`,
+        );
+      }
+      continue;
+    }
+    mkdirSync(dirname(dest), { recursive: true });
+    cpSync(source, dest);
+  }
+}
+
+export function filterCheck() {
+  let outDir = '';
+  let base = '/';
+  let command = 'serve';
+
+  return {
+    name: 'filter-check',
+    enforce: 'pre',
+    config() {
+      return {
+        optimizeDeps: { exclude: [PACKAGE] },
+      };
+    },
+    configResolved(config) {
+      outDir = resolveOutDir(config.root, config.build.outDir);
+      base = config.base || '/';
+      command = config.command;
+    },
+    resolveId(id) {
+      if (id === PACKAGE) return VIRTUAL;
+    },
+    async load(id) {
+      if (id !== VIRTUAL) return null;
+      const result = await build({
+        absWorkingDir: root,
+        entryPoints: [entry],
+        bundle: true,
+        format: 'esm',
+        platform: 'browser',
+        write: false,
+        legalComments: 'none',
+      });
+      return `const __filterCheckBase = ${JSON.stringify(base)};\n${result.outputFiles[0].text}`;
+    },
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => serveBaits(base, req, res, next));
+    },
+    configurePreviewServer(server) {
+      server.middlewares.use((req, res, next) => serveBaits(base, req, res, next));
+    },
+    closeBundle() {
+      if (command !== 'build') return;
+      copyBaits(outDir);
+    },
+  };
+}