Metadata-Version: 2.4
Name: term-chameleon
Version: 0.1.1
Summary: Adaptive contrast/readability toolkit for translucent terminals, starting with iTerm2.
Project-URL: Homepage, https://github.com/bodhi/term-chameleon
Project-URL: Repository, https://github.com/bodhi/term-chameleon
Project-URL: Issues, https://github.com/bodhi/term-chameleon/issues
Project-URL: Changelog, https://github.com/bodhi/term-chameleon/blob/main/CHANGELOG.md
Author: Term Chameleon contributors
License: MIT
License-File: LICENSE
Keywords: accessibility,contrast,iterm2,osc,terminal,transparency
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Terminals
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: iterm
Requires-Dist: iterm2>=2.9; extra == 'iterm'
Provides-Extra: visual
Requires-Dist: pillow>=10.0; extra == 'visual'
Description-Content-Type: text/markdown

# Term Chameleon

Term Chameleon is an adaptive contrast/readability toolkit for translucent terminals, starting with iTerm2 on macOS.

Glassy terminal themes look good until white text disappears over a bright window, black/dim text vanishes over dark blur, or iTerm2 Light/Dark profile variants silently override the intended palette. Term Chameleon provides static profile diagnostics/fixes plus live background-aware sampling, staging, and adaptation for iTerm2.

## Current status

This repository is prepared as `v0.1.1` / Python package version `0.1.1`: a dogfooded beta for static profile diagnostics, safe profile mutation, deterministic visual artifacts, live iTerm2 adaptation, controlled macOS GUI/screenshot QA, and real iTerm2 AutoLaunch watcher operation. Implemented:

- iTerm2 Dynamic Profile JSON parsing.
- Color conversion between hex and iTerm2 color dictionaries.
- WCAG contrast calculations.
- Static diagnostics for common glass-terminal readability failures.
- Conservative static fixer with dry-run, backups, deterministic JSON, and explainable changes.
- iTerm2 Dynamic Profile preset install flow, including optional AutoLaunch default-profile script.
- Manual readability mode switching for profile JSON files.
- OSC color sequence generation, including tmux passthrough wrapping.
- Dynamic watcher foundation via `watch-sim` risk classifier and hysteresis mode selector.
- iTerm2 live-adapter script generation/probe foundation for session-local Python API validation.
- Screen/image sampling one-shot adaptation via `sample` and `adapt-once`.
- Live adaptive watcher via `watch-live`, with dry-run, stable-sample, cooldown, duration, and real iTerm2 session-local apply modes.
- Deterministic E2E staging bundle that combines controlled backgrounds, ANSI pattern artifacts, visual simulation, screenshot capture, and screenshot pixel analysis.
- Screenshot contrast estimation for captured PNG/PPM artifacts.
- Text-row/glyph-aware screenshot contrast estimation for rendered terminal pattern captures.
- Live GUI staging that arranges controlled Safari background + iTerm2 ANSI pattern windows and can optionally capture/analyze the result with text-row contrast and pixel-cluster fallback.
- macOS `screencapture` probe and screenshot-test artifact foundation for screenshot-based visual tests.
- Long-running daemon packaging for continuous adaptation.
- Permission-free deterministic self-check command for post-install validation.
- Local readiness status command with human and JSON output.
- Guided setup command that runs deterministic checks and optionally installs the default profile.
- TOML config example, validation, and `--config` support for setup/watch-live/watch daemon flows.
- Watch daemon status and uninstall commands for AutoLaunch lifecycle management.
- Top-level release-readiness gate that composes deterministic checks, config validation, readiness, daemon, and live-stage checks.
- Cross-terminal detection (`terminal-info`) and OSC color sequence application for iTerm2, Kitty, Ghostty, and Alacritty.
- Adaptive Otsu thresholding for text-row glyph/background separation.
- Fixture tests for good and bad iTerm2 profiles.

Optional future refinements:

- Replace heuristic text-row detection with OCR/terminal-cell-aware glyph segmentation.
- Live session mutation for Kitty/Ghostty (currently OSC-only for non-iTerm2 terminals).
- PyPI publish via trusted publishing (requires pypi.org configuration).

## Beta release verification

Build and install the beta wheel locally:

```bash
uv build
python3 -m venv /tmp/term-chameleon-beta-venv
/tmp/term-chameleon-beta-venv/bin/pip install 'dist/term_chameleon-0.1.1-py3-none-any.whl[iterm]'
/tmp/term-chameleon-beta-venv/bin/term-chameleon setup --yes
/tmp/term-chameleon-beta-venv/bin/term-chameleon release-check --output-dir /tmp/term-chameleon-beta-release-check
/tmp/term-chameleon-beta-venv/bin/term-chameleon release-check --output-dir /tmp/term-chameleon-beta-live-check --live --live-stage --threshold 1.0
```

The real iTerm2 AutoLaunch watcher was dogfooded for this beta by installing the daemon, restarting iTerm2, verifying a single running watcher process, checking daemon status, and confirming screenshot sample artifacts were written.

See [CHANGELOG.md](CHANGELOG.md) for release notes.

## Use it

```bash
python3 -m venv ~/.local/share/term-chameleon/venv
~/.local/share/term-chameleon/venv/bin/pip install 'term-chameleon[iterm]'
~/.local/share/term-chameleon/venv/bin/term-chameleon setup --yes
~/.local/share/term-chameleon/venv/bin/term-chameleon release-check --live --live-stage --threshold 1.0
~/.local/share/term-chameleon/venv/bin/term-chameleon install-watch-daemon
~/.local/share/term-chameleon/venv/bin/term-chameleon watch-daemon-status
```

Restart iTerm2 after installing the daemon. The AutoLaunch script starts one long-running `watch-live` process and records its pid/log paths; use `watch-daemon-status` to inspect it and `uninstall-watch-daemon` to remove the AutoLaunch script. The daemon samples the whole screen by default for startup robustness; pass `install-watch-daemon --iterm-window` if you prefer front-iTerm-window sampling after confirming Accessibility/iTerm2 API startup behavior on your machine.

## CLI examples

Run a permission-free deterministic self-check after installation or inspect local readiness:

```bash
term-chameleon check --output-dir artifacts/check
term-chameleon release-check --output-dir artifacts/release-check
term-chameleon setup
term-chameleon setup --yes
term-chameleon setup --live
term-chameleon config-example --output ~/.config/term-chameleon/config.toml
term-chameleon config-check --config ~/.config/term-chameleon/config.toml
term-chameleon watch-live --config ~/.config/term-chameleon/config.toml --dry-run
term-chameleon status
term-chameleon status --live
term-chameleon status --json
```

`setup` is a guided flow: it runs deterministic checks and reports status. On first run, bare `setup` exits nonzero until a healthy profile exists; use `setup --yes` to install the generated profile, and `setup --live` to include live iTerm2 API/window readiness.

`release-check` is the top-level local gate. By default it is permission-free and writes JSON/Markdown reports; add `--config`, `--live`, `--daemon`, or `--live-stage` to include config validation, live iTerm2 probes, AutoLaunch health, or controlled Safari+iTerm2 screenshot QA.

`config-example` prints a commented TOML file. `config-check` validates value types, preset names, region shape, and unknown sections/keys. `watch-live`, `install-watch-daemon`, and `setup` accept `--config`; explicit CLI flags override config values.

Install a balanced preset into a target directory:

```bash
term-chameleon install --target-dir /tmp/iterm-dynamic-profiles --name "Adaptive Glass"
```

Install an iTerm2 AutoLaunch script that starts the live watcher whenever iTerm2 launches:

```bash
term-chameleon install-watch-daemon --dry-run
term-chameleon watch-daemon-status
term-chameleon install-watch-daemon
term-chameleon watch-daemon-status --json
term-chameleon uninstall-watch-daemon --dry-run
term-chameleon uninstall-watch-daemon
```

`uninstall-watch-daemon` removes the iTerm2 AutoLaunch script only; it does not stop an already-running watcher process or remove logs/pid files. It creates a backup by default unless `--no-backup` is passed.

Apply a manual readability mode to a profile JSON file:

```bash
term-chameleon mode bright-safe ~/Library/Application\ Support/iTerm2/DynamicProfiles/adaptive-glass.json --dry-run
```

Check iTerm2 Python API readiness and generate a conservative session-local adapter script:

```bash
term-chameleon iterm-api-check
term-chameleon iterm-connect-probe
term-chameleon iterm-window-bounds
term-chameleon iterm-live-script --preset balanced --output /tmp/term-chameleon-live.py
```

Probe macOS screenshot availability and generate controlled screenshot-test artifacts:

```bash
term-chameleon screenshot-probe
term-chameleon screenshot-probe --capture --output artifacts/screenshot-probe/screen.png
term-chameleon screenshot-contrast artifacts/screenshot-probe/screen.png --output-dir artifacts/screenshot-contrast
term-chameleon screenshot-text-contrast artifacts/screenshot-probe/screen.png --output-dir artifacts/screenshot-text-contrast
term-chameleon screenshot-test --output-dir artifacts/screenshot-test
term-chameleon screenshot-test --capture --output-dir artifacts/screenshot-test
term-chameleon background-html --output-dir artifacts/background-html
term-chameleon pattern-script --output-dir artifacts/pattern-script
term-chameleon e2e-stage tests/fixtures/iterm/good-dark-glass.json --output-dir artifacts/e2e-stage
term-chameleon live-stage --dry-run --output-dir artifacts/live-stage
term-chameleon live-stage --yes --capture --output-dir artifacts/live-stage
```

`live-stage --yes` is intentionally explicit because it activates Safari, opens the controlled background page, creates/resizes an iTerm2 window, writes the ANSI pattern command into that session, and may require macOS Automation/Accessibility/Screen Recording permissions. It leaves the staged windows open for inspection.

```bash
term-chameleon sample --screen --output artifacts/adapt/screen.png
term-chameleon sample --screen --iterm-window --output artifacts/adapt/iterm-window.png
term-chameleon sample --screen --region 0,0,800,600 --output artifacts/adapt/region.png
term-chameleon adapt-once tests/fixtures/iterm/good-dark-glass.json --screen --dry-run
term-chameleon watch-live --dry-run --duration 10 --interval 1 --stable 2
term-chameleon watch-live --dry-run --iterm-window --duration 10 --interval 1 --stable 2
term-chameleon watch-live --yes --iterm-window --duration 30 --interval 2 --stable 3 --cooldown 10
```

Manual live smoke test, once iTerm2 is running and the Python API is enabled:

```bash
scripts/live-iterm-smoke.sh
```

Run deterministic visual simulation:

```bash
term-chameleon visual-test tests/fixtures/iterm/good-dark-glass.json
```

Doctor a profile:

```bash
term-chameleon doctor tests/fixtures/iterm/bad-light-variant.json
term-chameleon doctor tests/fixtures/iterm/bad-light-variant.json --json
```

`doctor --json` emits machine-readable diagnostics after a profile loads successfully; profile load/parse errors still use the standard nonzero exit code with an error on stderr.

Preview fixes:

```bash
term-chameleon fix tests/fixtures/iterm/bad-light-variant.json --dry-run
```

Apply fixes to a copy:

```bash
cp tests/fixtures/iterm/bad-light-variant.json /tmp/profile.json
term-chameleon fix /tmp/profile.json --yes
term-chameleon doctor /tmp/profile.json
```

## Troubleshooting

**iTerm2 Python API not connected:**

Ensure iTerm2 is running and Python API support is enabled: iTerm2 → Settings → General → Magic → check "Enable Python API". Run `term-chameleon iterm-api-check` to verify.

**Screen Recording permission denied:**

macOS requires Screen Recording permission for `screencapture`. Grant it in System Settings → Privacy & Security → Screen Recording for the terminal running Term Chameleon.

**AutoLaunch daemon not starting:**

Verify the script exists and is executable:

```bash
term-chameleon watch-daemon-status
```

If the PID file is stale (process not running), remove it and restart iTerm2:

```bash
rm ~/Library/Application\ Support/term-chameleon/watch-live.pid
```

**Stale watcher process after uninstall:**

`uninstall-watch-daemon` removes the AutoLaunch script but does not kill a running watcher. Stop it manually:

```bash
kill "$(cat ~/Library/Application\ Support/term-chameleon/watch-live.pid)"
```

**Daemon CPU or disk usage:**

The daemon defaults to a 10-second sampling interval and prunes artifacts to the 200 most recent. To reduce overhead further, increase the interval via config or `--interval`.

**iTerm2 window bounds unavailable on startup:**

The daemon defaults to whole-screen sampling for startup robustness. If using `--iterm-window`, the watcher waits up to 60 seconds for iTerm2 to create a window before failing.

## Development

```bash
uv sync --extra dev
uv run pytest
uv run ruff check .
```

If you do not use `uv`:

```bash
python3 -m pytest
python3 -m term_chameleon.cli doctor tests/fixtures/iterm/bad-light-variant.json
```

## Safety principles

- Static analysis before mutation.
- `--dry-run` support for fixes.
- Timestamped backups before writing.
- Deterministic JSON output.
- Explainable diagnostics and fixes.
- No direct mutation of `~/Library/Preferences/com.googlecode.iterm2.plist` as the primary mechanism.

## Positioning

Term Chameleon is not just another terminal theme and does not claim to invent automatic contrast. Prior art includes iTerm2 Minimum Contrast, Apple Terminal contrast tweaking, Ghostty minimum contrast, terminal opacity/blur settings, CSS blend-mode/backdrop approaches, and WCAG/APCA contrast engines.

The intended differentiated direction is a live contrast controller for translucent terminal windows: sample or infer the actual visual environment behind the terminal, then adapt palette, opacity, blur, and contrast to keep text readable without giving up the glass effect.
