fix(macos): support title-based element lookup

[ZhengdaWang (zhengdawang443)]

Summary

Fix macOS Appium Mac2 element discovery for controls whose accessible text is exposed only through the title attribute, such as native context-menu items.

Snapshots, structured queries, explicit locators, semantic targets, and ambiguity diagnostics now preserve and match title.

Related issue

No issue linked. This fixes a verified macOS element-location failure and updates the public locator contract.

Design document

No separate design document. This change was implemented through a confirmed direct /spec-driven request and SPEC delta.

SPEC updates

Updated and confirmed before implementation:

• SPEC.md
• fsq_agent/core/SPEC.md
• fsq_agent/models/SPEC.md

The updated contracts define title as a supported macOS snapshot, query, and locator signal.

Changes

• Add title to the public MacOSLocator model.
• Preserve and clip title in compact macOS snapshots.
• Search title in structured element queries while retaining the complete value in generated locators.
• Include title in semantic target matching.
• Support explicit @title locator constraints.
• Preserve title in ambiguity candidate summaries.
• Add regression coverage for the complete title-location path.

Verification

• .venv/bin/python -m pytest tests/test_macos_elements.py tests/test_macos_harness.py tests/test_models.py -q
  • 84 passed
• .venv/bin/python -m pytest -q
  • 3168 passed, 12 skipped
• .venv/bin/ruff check fsq_agent/models/_core.py fsq_agent/drivers/macos/_elements.py fsq_agent/drivers/macos/_appium_mac2.py tests/test_macos_elements.py
  • Passed
• .venv/bin/ruff format --check fsq_agent/models/_core.py fsq_agent/drivers/macos/_elements.py fsq_agent/drivers/macos/_appium_mac2.py tests/test_macos_elements.py
  • Passed
• Pylance diagnostics reported no errors in changed production files.

Evidence

Live Appium Mac2 page source confirmed that native menu item text is exposed through title, including Save Link As… and Save Page As…. A title XPath query returned both matching elements.

No screenshots or generated artifacts are included.

Release or documentation impact

The public macOS locator schema now accepts title. No README, packaging, setup, or release workflow changes are required.

Checklist

Spec-driven development

• I reviewed root SPEC.md and every relevant module SPEC.md.
• Any required design and SPEC confirmation gates occurred before implementation.
• The implementation, tests, and documentation agree with the current confirmed SPEC files.
• I used the current confirmed SPEC files, not the design document, as the implementation source of truth.

Quality and safety

• I ran focused tests and required formatting or lint checks, or explained why a check was not applicable.
• I updated user-facing documentation when behavior or setup changed, or it is not applicable.
• I did not commit credentials, tokens, account data, personal data, local .env files, generated logs, reports, screenshots, or workspace output.
• I reviewed any included screenshots, videos, logs, reports, and Run artifacts for secrets, private paths, device identifiers, and account data.
• I did not add large binary media to Git history unless the repository already owns that exact artifact and the size is justified.