# Changelog

All notable changes to AXTerminator will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.8.0] - 2026-03-22

### Breaking
- **Python package removed.** PyPI versions yanked. Use the Rust binary only.
- Crate type changed from cdylib+rlib to rlib only.
- PyO3 dependency removed entirely — binary has zero Python linkage.

### Added

#### Tools (34 total, was 19)
- `ax_query`: natural language UI questions via SceneEngine
- `ax_analyze`: UI pattern detection (14 patterns), app state inference, action suggestions
- `ax_visual_diff`: pixel-level visual regression testing
- `ax_a11y_audit`: WCAG accessibility compliance audit (1.1.1, 1.3.1, 4.1.2)
- `ax_clipboard`: read/write system clipboard
- `ax_run_script`: AppleScript/JXA execution (blocked in safe/sandboxed mode)
- `ax_session_info`: server session state
- `ax_undo`: undo last N actions via Cmd+Z
- `ax_workflow_create/step/status`: durable multi-step workflows with checkpoint/resume
- `ax_record`: interaction recording for test generation
- `ax_track_workflow`: cross-app workflow pattern detection
- `ax_test_run`: black-box desktop testing
- `ax_app_profile`: Electron app metadata (VS Code, Slack, etc.)
- `ax_browser_launch/stop`: Docker browser containers (feature: docker)

#### MCP Protocol
- **Tasks API**: tasks/list, tasks/result, tasks/cancel — async tool execution
- **Sampling**: server advertises sampling capability, ax_find_visual returns
  screenshot + sampling request when client supports it
- **Resource subscriptions**: resources/subscribe, notifications/resources/updated
- **Progress notifications**: ax_get_tree, ax_test_run, ax_workflow_step emit progress
- **Elicitation**: destructive action gate on ax_click (confirm:true required)

#### Prompts (10 total, was 4)
- `troubleshooting`: when something fails
- `app-guide`: per-app playbook (Calculator, TextEdit, Safari, Chrome, Finder, Notes)
- `automate-workflow`: durable workflow creation guidance
- `debug-ui`: debug element-not-found issues
- `cross-app-copy`: cross-application data transfer
- `analyze-app`: comprehensive UI analysis

#### Resources (6 static + 4 templates)
- `axterminator://clipboard`: system clipboard contents
- `axterminator://workflows`: cross-app workflow patterns
- `axterminator://profiles`: Electron app profiles registry
- `axterminator://app/{name}/query/{question}`: natural language scene queries

#### Security Model
- 3-tier security modes: normal/safe/sandboxed (AXTERMINATOR_SECURITY_MODE)
- App allowlist/denylist (~/.config/axterminator/security.toml)
- Rate limiting (50 rps default, configurable)
- Action audit log (~/.local/share/axterminator/audit.jsonl)

#### AI Agent Support
- `llms.txt` at repo root for machine-readable installation
- MCP instructions with progressive disclosure (compact L1 → prompts L2)

### Changed
- `ax_find`: OR semantics for simple text queries (was AND), searches
  AXTitle + AXDescription + AXValue + AXLabel + AXIdentifier
- `ax_find`: semantic fallback via SemanticFinder when exact match fails
- `ax_find`: includes healing locator in response for session persistence
- `ax_click`: auto-falls-back to CGEvent coordinate click when AXPress unsupported
- `ax_click`: response includes element bounds
- `ax_connect`: returns `app_type` (native/electron/webview) via router detection
- `ax_screenshot`: uses CGWindowListCopyWindowInfo (was broken AppleScript)
- `ax_get_tree`: optional `format="llm"` for token-optimized output
- `tree` CLI: recursion works, shows bounds, disabled state, element count
- Search scoped to windows (excludes menus and system UI)

### Fixed
- Release binary linked to absolute Python framework path (crashes on every machine)
- Standalone binary used PyO3 before Python interpreter initialized
- Simple text search required ALL attributes to match (AND instead of OR)
- AXDescription and AXValue never checked during element search
- Tree CLI only printed one level (no recursion)
- Screenshot failed on most apps (AppleScript window-id lookup broken)

### Removed
- Python package (pyproject.toml, python/ directory, 12 test files)
- PyO3 dependency
- cdylib crate type
- Python-specific CI jobs (maturin develop, pytest)
- All Python references from documentation

## [0.6.1] - 2026-03-20

### Changed
- All dependencies upgraded to latest: pyo3 0.28, axum 0.8, rand 0.10,
  core-graphics 0.25, tungstenite 0.29, sysinfo 0.38, criterion 0.8
- Zero outdated dependencies (`cargo outdated` clean)

### Fixed
- Unused variable in app.rs (CI clippy --all-features)
- CI clippy failures, unnecessary cast, unused import

## [0.6.0] - 2026-03-20

### Fixed
- Speech recognition: capture at native 48kHz sample rate (was 16kHz header
  with 48kHz data, causing garbled audio unrecognizable by SFSpeechRecognizer)
- Speech recognition: pump CFRunLoop for callback delivery (was blocking RunLoop)
- Gesture recognition: TIP vs MCP knuckle comparison with confidence filtering
- Dangerous unwrap() on missing JSON-RPC id, NaN confidence, CString user input
- 3 doctest feature-gate issues (camera, spaces)

### Security
- pyo3 0.22 → 0.24.2 (RUSTSEC-2025-0020: buffer overflow)
- lru 0.12 → 0.16.3 (RUSTSEC-2026-0002: unsoundness)
- cargo audit: 0 advisories

### Changed
- Refactored 6 modules to meet 800 LOC quality gate (tools_extended, tools,
  resources, server, elicitation, camera)
- Release pipeline: crates.io + Homebrew auto-update on tag push
- CLI binary now included in GitHub Release assets
- README badges: crates.io version/downloads, PyPI, dependency status
- Issue/PR templates updated for MCP-first workflow

## [0.5.0] - 2026-03-19

### Added
- **MCP server rewrite in Rust** — 13 files, 8163 LOC replacing Python server.py
  - 12 core tools + 18 extended tools (30 total)
  - 5 resources (apps, tree, screenshot, state, displays)
  - 4 guided prompts (test-app, navigate-to, extract-data, accessibility-audit)
  - 9 elicitation scenarios for destructive/ambiguous operations
  - Tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint)
  - Bearer token auth + localhost-only for HTTP transport
  - Structured MCP logging + progress notifications
- **Audio capture** (`audio` feature) — CoreAudio microphone/system capture, SFSpeechRecognizer transcription, NSSpeechSynthesizer TTS
- **Camera + gesture detection** (`camera` feature) — AVFoundation single-frame capture, Vision hand pose detection with 7 gesture types
- **Virtual desktop management** (`spaces` feature) — CGSSpace private API: list/create/move/switch/destroy
- **Multi-monitor support** — negative coordinates, Retina scaling
- Homebrew formula
- Wiki (7 pages)
- SECURITY.md, CODE_OF_CONDUCT.md, issue/PR templates

### Fixed
- Gesture recognition: TIP vs MCP knuckle comparison, confidence filtering (#25)
- Speech recognition: TCC permission request + 30s timeout (#26)
- Speech recognition: pump CFRunLoop for SFSpeechRecognizer callback delivery (#27)
- Speech recognition: capture at native 48kHz sample rate — was writing 48kHz
  data with 16kHz WAV header, causing 3x slowdown and unrecognizable audio (#27)
- Camera permission request when status undetermined
- PyO3 extension-module decoupled from CLI binary via `python-ext` feature flag
- bytes 1.11.0 integer overflow (RUSTSEC-2026-0007)
- Dangerous unwrap() on missing JSON-RPC id, NaN confidence, CString user input
- Removed Pickle virtual audio drivers intercepting default input device

### Security
- pyo3 0.22 → 0.24.2 (RUSTSEC-2025-0020: buffer overflow in PyString)
- lru 0.12 → 0.16.3 (RUSTSEC-2026-0002: IterMut unsoundness)

### Changed
- README rewritten: MCP server first, no superlatives, honest claims only
- Audio module split from 1567 LOC monolith to 5-file module (max 436 LOC)
- MCP tools_extended.rs (2640 LOC) split into 6 focused modules
- 5 additional modules split to meet 800 LOC quality gate
- camera.rs refactored to camera/ module directory
- Issue/PR templates updated for MCP-first workflow
- Gateway config points to release binary
- Published v0.5.0 to crates.io

## [0.4.0] - 2026-03-19

### Added
- **Query-based scene understanding** with encode-once keystone architecture (#4)
- **Two-stage screen intent extraction** pipeline (#5)
- **Copilot-readable state injection** (`useCopilotReadable`) (#6)
- **Persistent element references** with fingerprint-based WeakRef tracking (#7)
- **Semantic element find** and Electron DevTools Protocol integration (#8, #9)
- **Cross-app workflow intelligence** with pattern detection and automation (#10)
- **Proactive desktop copilot** with rule-based context suggestions (#11)
- **Triple understanding** and durable automation steps (#12, #16)
- **Workflow recording** and blackbox desktop testing (#13, #14)
- **Electron app skill profiles** — 5 built-in profiles + extensible registry (#15)
- **Docker browser test targets** via Neko containers for CI (#18)
- MkDocs documentation site with benchmarks
- Comprehensive tool comparison table (vs XCUITest, Appium, PyAutoGUI, Maestro)
- Python type stubs (`.pyi`) for full IDE support
- mediar-ai/terminator acknowledgement in README

### Fixed
- MCP server: VLM fallback and method calls on AXElement
- CI: formatting and skip accessibility-dependent tests
- Clippy: 10 fixes across the codebase for clean `cargo clippy` output
- 6 documentation link fixes (broken intra-doc links, stale references)

### Changed
- Updated OpenAI model references to current models (GPT-4o, GPT-5)
- README rewritten with verified benchmark numbers and factual claims
- Module-level documentation improvements with `//!` doc headers and examples
- Publication cleanup: factual claims, honest benchmarks, no superlatives

### Refactored
- Extracted `copilot_extract.rs` and `healing_match.rs` to fix LOC violations
- Registered new modules in `lib.rs`

## [0.3.2] - 2026-03-18

### Added
- Python type stubs (`.pyi`) for full IDE support — autocomplete, type checking, and inline documentation for all Rust-backed classes (`AXApp`, `AXElement`, `HealingConfig`, `ActionMode`) and module-level functions
- Dead code annotations (`#[allow(dead_code)]`) for planned XPath healing strategy infrastructure in `healing_match.rs`, `router.rs`, `sync.rs`, and `accessibility.rs`

### Fixed
- **Clippy cleanup**: 10 fixes across the codebase — resolved all warnings for clean `cargo clippy` output
- 6 documentation link fixes across module docs (broken intra-doc links, stale references)

### Changed
- Module-level documentation improvements — all public modules now have `//!` doc headers with examples
- Docker browser test targets via Neko containers for CI (#18)
- Electron app skill profiles — 5 built-in profiles + registry (#15)
- Proactive desktop copilot with rule-based context suggestions (#11)
- Cross-app workflow intelligence with pattern detection (#10)
- Workflow recording and blackbox desktop testing (#13, #14)
- Query-based scene understanding with encode-once keystone (#4)
- Semantic element find and Electron DevTools Protocol (#8, #9)
- Triple understanding and durable automation steps (#12, #16)
- Persistent element references with fingerprint-based WeakRef tracking (#7)

## [0.3.1] - 2026-02-01

### Added
- Real-world examples (Safari, Finder, TextEdit workflows)
- Chrome recorder browser extension

## [0.3.0] - 2026-01-19

### Added
- CLI tool (`axterminator inspect`, `axterminator tree`, `axterminator record`)
- Action recording and playback
- pytest plugin (`pytest-axterminator`)
- Ollama local VLM backend
- MCP server for Claude Code integration

## [0.2.1] - 2026-01-18

### Added
- PyPI publishing workflow
- XPC sync module
- API documentation

## [0.2.0] - 2026-01-17

### Added
- Gemini VLM backend
- VLM examples
- MLX/Claude/GPT-4V visual element detection

## [0.1.0] - 2026-01-10

### Added
- Initial release
- Background GUI testing (no focus stealing)
- 7-strategy self-healing locators
- Python bindings via PyO3
- macOS Accessibility API integration
- ~379 us element access (measured on M1 MacBook Pro)
