# Development Guide

This page is for contributors changing patch code, injected assets, tests, or
docs.

## Setup

```powershell
git clone https://github.com/JSukar/IMVU-TOOLKIT.git
cd IMVU-TOOLKIT
python -m pip install -e ".[dev]"
```

Run checks:

```powershell
ruff check src tests
pytest
```

Build dependencies are separate:

```powershell
python -m pip install -e ".[build]"
```

## Project Conventions

- Prefer the unified CLI in docs and examples.
- Keep root-level legacy scripts working.
- Add patch markers for injected or rewritten content.
- Back up before writing patched IMVU files.
- Support `--restore` for mutating patch scripts.
- Validate expected signatures before modifying files.
- Keep changes focused and update docs for user-visible behavior.

## Adding or Changing Emoji Behavior

Main locations:

```text
src/imvu_toolkit/patches/emoji/
emoji_assets/js/
tests/fixtures/
tests/test_emoji_patch.py
tests/test_jar_integration.py
```

If the emoji catalog changes, regenerate:

```powershell
python -m imvu_toolkit emoji generate-list
```

## Adding or Changing DPI Behavior

Main locations:

```text
patches/dpi/
src/imvu_toolkit/patches/dpi/registry.py
scripts/imvu_dpi_runtime_probe.py
scripts/audit_imvu_dpi_probe.py
scripts/compare_imvu_probes.py
```

If a new DPI script should be exposed through the CLI, add it to
`DPI_SCRIPTS` in `src/imvu_toolkit/patches/dpi/registry.py`.

## Adding or Changing Tool Scripts

Main locations:

```text
scripts/
src/imvu_toolkit/tools/runner.py
```

If a new utility should be exposed through the CLI, add it to `TOOL_SCRIPTS` in
`src/imvu_toolkit/tools/runner.py`.

## Tests

Use fixture-based tests for deterministic transforms. The test suite should not
require a live IMVU install.

Helpful commands:

```powershell
pytest tests/test_emoji_patch.py
pytest tests/test_jar_integration.py
pytest tests/test_installer_runner.py
```

## Docs

Update the wiki for workflow guidance and update the reference docs for deeper
technical explanations:

```text
docs/wiki/
docs/architecture.md
docs/dpi-patches.md
docs/compatibility.md
docs/FAQ.md
```

Update `CHANGELOG.md` under `[Unreleased]` for user-visible changes.