Tactual

Анализатор стоимости навигации для программ чтения с экрана. Измеряет, насколько сложно пользователям вспомогательных технологий обнаруживать, находить и использовать интерактивные элементы в вебе.

Что он делает

Существующие инструменты доступности проверяют соответствие стандартам — корректен ли ARIA? Достаточен ли коэффициент контрастности?

Tactual измеряет стоимость навигации — сколько действий нужно совершить пользователю программы чтения с экрана, чтобы добраться до кнопки оформления заказа? Что произойдет, если он промахнется? Сможет ли он вообще обнаружить, что она существует?

Инструмент работает путем захвата снимков доступности Playwright, построения графа навигации и оценки каждого целевого элемента в соответствии с профилем вспомогательной технологии.

Установка

# For CLI usage
npm install tactual playwright

# For MCP server usage (AI tools)
npm install tactual playwright @modelcontextprotocol/sdk

Playwright и @modelcontextprotocol/sdk являются необязательными зависимостями (peer dependencies). Playwright необходим для CLI и анализа страниц. MCP SDK требуется для запуска сервера tactual-mcp. Ни то, ни другое не нужно, если вы используете только библиотечный API с предварительно захваченными состояниями.

Быстрый старт

CLI

# Analyze a URL (default profile: generic-mobile-web-sr-v0)
tactual analyze-url https://example.com

# Analyze with a specific AT profile
tactual analyze-url https://example.com --profile voiceover-ios-v0

# Explore hidden UI (menus, tabs, dialogs, disclosures)
tactual analyze-url https://example.com --explore

# Output as JSON, Markdown, or SARIF
tactual analyze-url https://example.com --format json --output report.json
tactual analyze-url https://example.com --format sarif --output report.sarif

# Compare two analysis runs
tactual diff baseline.json candidate.json

# List available AT profiles
tactual profiles

# Run benchmark suite
tactual benchmark

# Initialize a tactual.json config file
tactual init

Библиотечный API

import { analyze, getProfile } from "tactual";
import { captureState } from "tactual/playwright";
import { chromium } from "playwright";

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto("https://example.com");

const state = await captureState(page);
await browser.close();

const profile = getProfile("generic-mobile-web-sr-v0");
const result = analyze([state], profile);

for (const finding of result.findings) {
  console.log(finding.targetId, finding.scores.overall, finding.severity);
}

MCP-сервер

Tactual включает MCP-сервер для использования ИИ-агентами:

# Start the MCP server (stdio transport — default)
tactual-mcp

# Start with HTTP transport (for hosted platforms, remote clients)
tactual-mcp --http              # listens on http://127.0.0.1:8787/mcp
tactual-mcp --http --port=3000  # custom port (or set PORT env var)
tactual-mcp --http --host=0.0.0.0  # bind to all interfaces (default: 127.0.0.1)

Доступные инструменты MCP:

Настройка для ИИ-инструмента

Сначала установите необходимые пакеты в вашем проекте:

npm install tactual playwright @modelcontextprotocol/sdk

Claude Code — добавьте в .mcp.json в корне проекта:

{
  "mcpServers": {
    "tactual": {
      "type": "stdio",
      "command": "npx",
      "args": ["tactual-mcp"]
    }
  }
}

GitHub Copilot — добавьте в .copilot/mcp.json или ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "tactual": {
      "type": "stdio",
      "command": "npx",
      "args": ["tactual-mcp"]
    }
  }
}

Cursor / Windsurf / Cline — тот же формат в конфигурации MCP вашего редактора:

{
  "mcpServers": {
    "tactual": {
      "command": "npx",
      "args": ["tactual-mcp"]
    }
  }
}

Напрямую (глобальная установка) — если вы предпочитаете не использовать npx:

npm install -g tactual playwright
tactual-mcp  # starts the MCP server on stdio

GitHub Actions

Используйте составное действие (composite action) из GitHub Actions Marketplace:

jobs:
  a11y:
    runs-on: ubuntu-latest
    steps:
      - name: Analyze accessibility
        uses: tactual-dev/tactual@v0.2.1
        with:
          url: https://your-app.com
          explore: "true"
          fail-below: "70"

Действие устанавливает Tactual и Playwright, запускает анализ, загружает SARIF в GitHub Code Scanning и прерывает сборку, если средний балл ниже порогового значения. Выводит average-score и result-file для последующих шагов.

Или используйте CLI напрямую для большего контроля:

- name: Install Tactual
  run: npm install tactual playwright

- name: Install browsers
  run: npx playwright install chromium --with-deps

- name: Run accessibility analysis
  run: npx tactual analyze-url https://your-app.com --format sarif --output results.sarif --threshold 70

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Конфигурация

Флаги CLI

Options:
  -p, --profile <id>              AT profile (default: generic-mobile-web-sr-v0)
  -f, --format <format>           json | markdown | console | sarif (default: console)
  -o, --output <path>             Write to file instead of stdout
  -d, --device <name>             Playwright device emulation
  -e, --explore                   Explore hidden branches
  --explore-depth <n>             Max exploration depth (default: 3)
  --explore-budget <n>            Max exploration actions (default: 50)
  --explore-max-targets <n>       Max accumulated targets before stopping (default: 2000)
  --exclude <patterns...>         Exclude targets by name/role glob
  --exclude-selector <css...>     Exclude elements by CSS selector
  --focus <landmarks...>          Only analyze within these landmarks
  --suppress <codes...>           Suppress diagnostic codes
  --top <n>                       Show only worst N findings
  --min-severity <level>          Minimum severity to report
  --threshold <n>                 Exit non-zero if avg score < N
  --config <path>                 Path to tactual.json
  --no-headless                   Headed browser (for bot-blocked sites)
  --timeout <ms>                  Page load timeout (default: 30000)
  --probe                         Run keyboard probes (focus, activation, Escape, Tab)
  --wait-for-selector <css>       Wait for selector before capturing (for SPAs)
  --wait-time <ms>                Additional wait after page load
  --storage-state <path>          Playwright storageState JSON for authenticated pages
  --summary-only                  Return only summary stats, no individual findings
  -q, --quiet                     Suppress info diagnostics

tactual.json

Создайте с помощью tactual init или вручную:

{
  "profile": "voiceover-ios-v0",
  "exclude": ["easter*", "admin*", "debug*"],
  "excludeSelectors": ["#easter-egg", ".admin-only", ".third-party-widget"],
  "focus": ["main"],
  "suppress": ["possible-cookie-wall"],
  "threshold": 70,
  "priority": {
    "checkout*": "critical",
    "footer*": "low",
    "analytics*": "ignore"
  }
}

Конфигурация автоматически определяется из рабочей директории (tactual.json или .tactualrc.json). Флаги CLI объединяются с настройками конфигурации и переопределяют их.

Профили вспомогательных технологий (AT)

Профили определяют стоимость каждого навигационного действия, веса размерностей оценки, costSensitivity (масштабирует кривую затухания достижимости) и контекстно-зависимые модификаторы. Подробности реализации см. в src/profiles/.

Оценка

Каждая цель получает вектор оценки из 5 измерений:

Веса измерений варьируются в зависимости от профиля:

Композитная оценка: Взвешенное среднее геометрическое: overall = exp(sum(w_i * ln(score_i)) / sum(w_i)) - interopRisk. Каждое измерение перед логарифмированием приводится к минимуму 1, чтобы избежать log(0). Это означает, что ноль в любом измерении резко снижает общую оценку — вы не можете управлять тем, до чего не можете добраться.

Диапазоны серьезности:

Диагностика

Tactual обнаруживает и сообщает, когда анализ может быть ненадежным:

Исследование

Флаг --explore активирует ограниченное исследование ветвей:

• Открывает меню, вкладки, раскрывающиеся списки, аккордеоны и диалоги

• Захватывает новые состояния доступности из скрытого UI

• Помечает обнаруженные цели как requiresBranchOpen

• Соблюдает бюджеты глубины, количества действий, количества целей и новизны

• Политика безопасных действий блокирует деструктивные взаимодействия

Исследование полезно для страниц со значительным скрытым UI (например, выпадающие меню, интерфейсы с вкладками, модальные диалоги).

Кандидаты для исследования сортируются по стабильному ключу (роль + имя) перед итерацией, поэтому один и тот же контент страницы дает одинаковый порядок исследования при разных запусках.

Бюджеты исследования

Обнаружение SPA-фреймворков

Tactual определяет, когда контент SPA отрендерился, перед захватом дерева доступности. Обнаруживаемые фреймворки: React, Next.js, Vue, Nuxt, Angular, Svelte и SvelteKit. Также проверяются сигналы стандартного HTML5-контента (ориентиры, заголовки, навигация, ссылки). Для SPA, не охваченных автоопределением, используйте --wait-for-selector (CLI) или waitForSelector (MCP/API), чтобы указать CSS-селектор, сигнализирующий о том, что приложение гидратировалось.

После первоначального обнаружения фреймворка Tactual использует опрос на основе сходимости — многократное создание снимков дерева доступности до тех пор, пока количество целей не стабилизируется, — что работает независимо от фреймворка.

Риск интероперабельности

Tactual включает статический снимок данных о поддержке ролей/атрибутов ARIA, полученных из a11ysupport.io и проекта ARIA-AT. Роли с известными пробелами в поддержке между AT/браузерами получают штраф за риск интероперабельности.

Рекомендации по формату вывода

Все форматы, кроме SARIF, выдают обобщенный вывод: статистику, сгруппированные проблемы и худшие результаты (ограничено 15). SARIF ограничен 25 результатами. Когда вывод усекается, вверху появляется примечание.

Для использования MCP sarif является форматом по умолчанию и рекомендуется. Используйте summaryOnly: true для минимальной проверки работоспособности (~835 байт: статистика, счетчики серьезности, топ-3 проблемы).

Калибровка

Tactual включает фреймворк калибровки (src/calibration/, экспортируется как tactual/calibration) для настройки параметров оценки на основе наборов данных с известными результатами. Подробности см. в docs/CALIBRATION.md.

Разработка

npm install                    # Install dependencies
npm run build                  # Build with tsup
npm run test                   # Run unit + integration tests
npm run test:benchmark         # Run benchmark suite
npm run typecheck              # TypeScript type checking
npm run lint                   # ESLint

Безопасность

Песочница браузера

Tactual всегда запускает Playwright с включенной по умолчанию песочницей Chromium. Он никогда не отключает веб-безопасность и не изменяет модель безопасности браузера. Все взаимодействия со страницей происходят внутри стандартной песочницы процесса Chromium.

Политика безопасных действий

Когда исследование включено (--explore), Tactual классифицирует интерактивные элементы на три уровня перед их активацией:

Это эвристика на основе ключевых слов — она не может обнаружить семантический обман (например, кнопку «Сохранить», которая на самом деле удаляет данные) или проверить поведение на стороне сервера. Для использования в продакшене всегда запускайте исследование в доверенных или изолированных средах.

Валидация URL

Все URL проверяются перед навигацией. Частные/внутренние диапазоны IP и схемы, отличные от HTTP(S), отклоняются по умолчанию.

Лицензия

Apache-2.0