# Image Optimization Redesign Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Restore the prior image/code state, create an `assets_backup` copy, and re-run image optimization so only materially beneficial conversions are adopted while oversized images are compressed to a better size/quality point.

**Architecture:** Revert only the previous assistant-generated changes back to the repository baseline, then operate from that clean baseline with a standalone Python optimizer script. The script will evaluate candidates per file, keep the better format, update references only for accepted conversions, and emit a report for verification.

**Tech Stack:** Python 3, `unittest`, ImageMagick `magick`, git, static HTML/CSS/JS assets

---

### Task 1: Restore Baseline And Create Backup

**Files:**
- Create: `assets_backup/**`
- Modify: `.gitignore`
- Modify: `assets/css/about.css`
- Modify: `assets/css/css.css`
- Modify: `assets/css/history.css`
- Modify: `assets/css/style.css`
- Modify: `*.html`
- Modify: `classiccase/*.html`
- Modify: `assets/images/**/*.{png,jpg,jpeg,gif}`
- Delete: `assets/images/**/*.webp`
- Delete: `huace/arrow.webp`
- Delete: `backup/original-images-20260414-155153.tar.gz`
- Delete: `scripts/optimize_images.py`

- [ ] **Step 1: Capture the assistant-created delta**

Run:
```bash
git diff --name-only
```
Expected: only the previously assistant-modified image, html, css, `.gitignore`, and generated `webp`/script artifacts are listed.

- [ ] **Step 2: Restore tracked files to repository baseline**

Run:
```bash
git restore --source=HEAD -- .gitignore assets/css/about.css assets/css/css.css assets/css/history.css assets/css/style.css changzhan.html chuandai.html classiccase.html classiccase/ index.html contact.html company.html company2.html culture.html dianshang.html footer.html header.html ilog.html jining.html joinus.html new_1.html new_2.html new_3.html new_5.html new_6.html product_Logistics.html product_eCommerce.html product_ecommerce_bctp.html product_ecommerce_freight_booking.html product_ecommerce_net_cargo.html product_ecommerce_obh.html product_full_logistics_chain_cargo_agent.html product_full_logistics_chain_platform.html product_full_logistics_chain_ship_agent.html product_full_logistics_chain_vehicle_transport.html product_full_logistics_chain_warehouse.html product_port.html product_port_cdi.html product_port_cdi_bulk.html product_port_cdi_container.html product_shipping.html product_shipping_boat.html product_shipping_company.html solution_inland_river_shipping.html solution_logistics_chain.html solution_port_supply_chain.html solution_supply_chain.html tech.html yunmatou.html assets/images huace/arrow.png
```
Expected: tracked files revert to `HEAD`.

- [ ] **Step 3: Remove generated artifacts**

Run:
```bash
find assets/images -type f -name '*.webp' -delete
rm -f huace/arrow.webp backup/original-images-20260414-155153.tar.gz scripts/optimize_images.py
```
Expected: previously generated `webp` files and old helper artifacts are removed.

- [ ] **Step 4: Create a full assets backup**

Run:
```bash
rm -rf assets_backup
cp -a assets assets_backup
```
Expected: `assets_backup` exists as a byte-for-byte working backup of the restored baseline assets tree.

- [ ] **Step 5: Verify the backup and restore state**

Run:
```bash
git status --short
find assets_backup -maxdepth 2 -type d | sort | sed -n '1,20p'
```
Expected: only `assets_backup/` is untracked before the new optimization work begins.

### Task 2: Add Red-Green Coverage For Selection Rules

**Files:**
- Create: `tests/test_optimize_assets.py`
- Create: `scripts/optimize_assets.py`

- [ ] **Step 1: Write the failing tests**

```python
import unittest
from pathlib import Path

from scripts.optimize_assets import should_keep_conversion, classify_large_image


class OptimizeAssetsRulesTest(unittest.TestCase):
    def test_rejects_webp_when_not_smaller_than_source(self) -> None:
        self.assertFalse(should_keep_conversion(120_000, 123_000))

    def test_accepts_materially_smaller_webp_for_large_file(self) -> None:
        self.assertTrue(should_keep_conversion(500_000, 430_000))

    def test_flags_large_by_filesize(self) -> None:
        self.assertTrue(classify_large_image(301_000, 1200, 900))

    def test_flags_large_by_dimensions(self) -> None:
        self.assertTrue(classify_large_image(120_000, 3000, 1800))
```

- [ ] **Step 2: Run the tests to confirm RED**

Run:
```bash
python3 -m unittest tests.test_optimize_assets -v
```
Expected: FAIL with import or symbol errors because `scripts/optimize_assets.py` does not exist yet.

- [ ] **Step 3: Write the minimal implementation**

```python
def should_keep_conversion(source_size: int, candidate_size: int) -> bool:
    savings = source_size - candidate_size
    if savings <= 0:
        return False
    if source_size < 150 * 1024:
        return savings >= 8 * 1024
    return (savings / source_size) >= 0.05


def classify_large_image(source_size: int, width: int, height: int) -> bool:
    return source_size > 300 * 1024 or max(width, height) > 2560
```

- [ ] **Step 4: Run the tests to confirm GREEN**

Run:
```bash
python3 -m unittest tests.test_optimize_assets -v
```
Expected: PASS with 4 tests run successfully.

### Task 3: Implement The Optimizer And Rewrite References

**Files:**
- Modify: `scripts/optimize_assets.py`
- Test: `tests/test_optimize_assets.py`
- Modify: `assets/css/**/*.css`
- Modify: `*.html`
- Modify: `classiccase/*.html`
- Modify: `product_*.html`
- Modify: `solution_*.html`

- [ ] **Step 1: Expand tests for path rewriting and candidate selection**

```python
    def test_prefers_original_when_candidate_savings_is_below_threshold(self) -> None:
        self.assertFalse(should_keep_conversion(200_000, 191_000))
```

- [ ] **Step 2: Run the tests to confirm RED**

Run:
```bash
python3 -m unittest tests.test_optimize_assets -v
```
Expected: FAIL on the new threshold case.

- [ ] **Step 3: Implement the full optimizer**

```python
# Main behavior:
# 1. Walk assets image files from the restored baseline.
# 2. For each image, optimize original format in place only if smaller.
# 3. For large images, evaluate multiple quality/resize candidates.
# 4. Generate webp only when it beats the optimized source and passes thresholds.
# 5. Update text references only for accepted conversions.
# 6. Emit a summary report with baseline and final totals.
```

- [ ] **Step 4: Run targeted verification**

Run:
```bash
python3 -m unittest tests.test_optimize_assets -v
python3 scripts/optimize_assets.py
```
Expected: tests pass; script prints accepted conversions, skipped conversions, and size totals.

### Task 4: Final Verification

**Files:**
- Verify: `assets/**`
- Verify: `assets_backup/**`
- Verify: `*.html`
- Verify: `assets/css/*.css`

- [ ] **Step 1: Verify there are no missing accepted references**

Run:
```bash
python3 scripts/optimize_assets.py --check
```
Expected: exit 0 with no missing rewritten references.

- [ ] **Step 2: Verify resulting size totals**

Run:
```bash
du -sh assets assets_backup
find assets -type f \\( -iname '*.webp' -o -iname '*.png' -o -iname '*.jpg' -o -iname '*.jpeg' -o -iname '*.gif' \\) -printf '%s\n' | awk '{s+=$1} END {printf "assets raster total: %.2f MB\n", s/1024/1024}'
```
Expected: `assets_backup` remains as backup; `assets` shows reduced effective payload compared with the restored baseline.

- [ ] **Step 3: Verify git diff is scoped correctly**

Run:
```bash
git status --short
```
Expected: only the intended backup, script, tests, optimized images, and rewritten references are listed.