# Adaptive Images — WordPress Plugin

Intercepts image requests via `.htaccess` rewrites, detects the requesting device's screen dimensions (via a JS-set cookie), resizes images on first request using PHP GD, caches them, and serves the closest matching size transparently — with no changes to theme markup or HTML.

## Repository layout

```
trunk/    Active development (deploy to WP plugin repo)
tags/     Released versions
assets/   Plugin directory artwork (banners, icons, screenshots)
```

## Key files in trunk/

| File | Role |
|---|---|
| `adaptive-images.php` | Plugin entry point; loads init file |
| `adaptive-images-init.php` | Registers all WordPress hooks and includes |
| `adaptive-images-plugin.php` | Shared utility functions (settings, path resolution, GD checks) |
| `adaptive-images-front.php` | Injects JS into `wp_head`; sets `resolution` cookie (width × pixel-ratio) |
| `adaptive-images-script.php` | **Standalone** image handler called directly by Apache/Nginx; reads cookie, resizes via GD, writes cache |
| `adaptive-images-actions.php` | Manages `.htaccess` rewrite stanza on activate/deactivate; cache deletion |
| `adaptive-images-admin.php` | Settings page UI (breakpoints, JPEG quality, cache dir, CDN mode, etc.) |
| `adaptive-images-debug.php` | Admin diagnostics panel |
| `adaptive-images-upgrade.php` | Settings migration between plugin versions |
| `uninstall.php` | Full cleanup on plugin deletion |

## Request flow

1. Browser JS reads `screen.width` / `devicePixelRatio`, writes `resolution` cookie.
2. Apache `.htaccess` rewrites JPEG/PNG/GIF requests to `adaptive-images-script.php`.
3. Script reads cookie → selects nearest breakpoint → serves cached resized image (or creates it via GD on first hit).
4. Bots / unknown devices fall back to the original image.

## Supported image formats

- JPEG, PNG, GIF (non-animated) — **supported**
- WebP, AVIF, animated GIF — **not yet supported**

## WordPress installation types

The plugin must correctly handle all five of these setups — they affect settings saving, `.htaccess` generation, and image path resolution:

| # | WP files location | `siteurl` (WP address) | `home` (site address) |
|---|---|---|---|
| 1 | `/public_html/` (root) | `/` | `/` |
| 2 | `/public_html/wordpress/` | `/wordpress` | `/wordpress` |
| 3 | `/public_html/wordpress/` (hidden) | `/wordpress` | `/` |
| 4 | `/public_html/wordpress/` | `/wordpress` | `/` |
| 5 | `/public_html/` (root) | `/` | `/` but `/wp-content` renamed |

> Cases 3 and 4 represent the classic "WordPress in subdirectory" pattern where the WP core files live under `/wordpress` but the public-facing site is served from `/`. The distinction matters for `.htaccess` rewrite base paths.

## CDN / reverse-proxy

Experimental support available via settings. Adds a query-string parameter to image URLs so CDNs can cache per resolution. Does **not** work with CDNs that serve images from a different subdomain.

## Breakpoints (defaults)

`1024px`, `640px`, `480px` — configurable in settings. HiDPI / retina support is optional.