commit 88a0531d90b6b7c688b66c662d8a03f4d8e32b6a
Author: Kevin Bataille <kbe@kev1.net>
Date:   Sun Sep 13 09:20:32 2026 +0200

    Add initial design document for WP Recache

diff --git a/docs/plans/2026-09-13-wprecache-design.md b/docs/plans/2026-09-13-wprecache-design.md
new file mode 100644
index 0000000..462550c
--- /dev/null
+++ b/docs/plans/2026-09-13-wprecache-design.md
@@ -0,0 +1,226 @@
+# WP Recache — Open Source Performance Plugin
+
+## Overview
+
+Create a commercial-grade WordPress performance plugin with feature parity to WP Rocket, implemented via clean-room methodology. The plugin will be open source (GPL-2.0+) and provide page caching, file optimization, and image optimization.
+
+## Clean-Room Methodology
+
+### Rules
+
+1. **No code reuse.** Never copy, paste, or adapt any PHP/JS/CSS from WP Rocket.
+2. **Feature specs only.** Document what WP Rocket does from a *user perspective* (UI behavior, options, output), not how it's implemented.
+3. **Independent implementation.** All code written from scratch using WordPress APIs and standard libraries.
+4. **Documentation trail.** Keep records of the specification process to prove independent development.
+
+### What We Study (User Perspective)
+
+- WP Rocket admin UI: what settings exist, what they control
+- Frontend output: what HTML/JS/CSS changes appear after activation
+- Behavior: when cache clears, what gets optimized, what's excluded by default
+- Performance: what metrics improve
+
+### What We Ignore
+
+- PHP source code structure
+- Internal class/function naming
+- Specific implementation patterns
+- Hook naming conventions
+
+## Feature Specifications
+
+### 1. Page Cache
+
+**User-facing behavior:**
+- On first anonymous visit, generates static HTML file
+- Subsequent anonymous visits serve the static file directly
+- Cache auto-purges when content is published/updated
+- Manual purge available from admin bar and settings page
+- Excludes logged-in users, cart/checkout pages, specific URLs
+- Separate cache for mobile devices (optional)
+- Preload/crawl sitemap to warm cache
+
+**Technical approach (independent implementation):**
+- Use WordPress `advanced-cache.php` drop-in
+- Output buffering via `ob_start()` / `ob_get_contents()` / `ob_end_flush()`
+- Cache files stored in `wp-content/cache/`
+- Serve cached files via direct file read before WordPress loads
+- Use WordPress rewrite rules for cache detection
+
+### 2. File Optimization — CSS
+
+**User-facing behavior:**
+- Minify CSS files (remove whitespace, comments)
+- Combine CSS files into fewer requests
+- Defer non-critical CSS loading
+- Remove unused CSS (RUCSS — Remove Unused CSS)
+- Inline critical CSS for above-the-fold content
+- Async CSS loading
+
+**Technical approach:**
+- Use CSS minification library (e.g., `natanielrodman/css-minify` or similar)
+- Parse CSS to identify critical path selectors
+- Output buffering to detect and modify `<link>` tags
+- Generate critical CSS via headless browser or parser
+
+### 3. File Optimization — JavaScript
+
+**User-facing behavior:**
+- Minify JavaScript files
+- Combine JavaScript files
+- Defer JavaScript loading (load after HTML parsed)
+- Delay JavaScript execution (load on user interaction)
+- Remove jQuery Migrate
+- Delay inline scripts
+
+**Technical approach:**
+- Use JavaScript minification (e.g., `tedivm/jshrink` or similar)
+- Output buffering to modify `<script>` tags
+- Add `defer` or `async` attributes
+- Wrap scripts in event listeners for delay functionality
+
+### 4. Image Optimization
+
+**User-facing behavior:**
+- Lazy load images (load when entering viewport)
+- Convert images to WebP/AVIF format
+- Optimize image compression
+- Add missing width/height attributes (CLS prevention)
+- Placeholder images while loading
+
+**Technical approach:**
+- Use `loading="lazy"` attribute (native lazy loading)
+- Use WordPress `wp_image_editor` APIs for format conversion
+- Use Imagick/GD for compression
+- Generate WebP/AVIF variants on upload
+
+### 5. Additional Features
+
+**Critical CSS:**
+- Generate critical CSS for above-the-fold content
+- Inline critical CSS, defer full stylesheet
+- Per-page critical CSS generation
+
+**Preload:**
+- Preload key requests (fonts, critical resources)
+- DNS prefetch for external domains
+- Prefetch for likely next pages
+
+**Database Optimization:**
+- Clean post revisions
+- Clean auto-drafts
+- Clean trashed posts
+- Optimize database tables
+
+## Architecture
+
+### Plugin Structure
+
+```
+wp-recache/
+├── wp-recache.php                 # Main plugin file
+├── uninstall.php                  # Clean uninstall
+├── composer.json                  # Dependencies
+├── readme.txt                     # WordPress.org readme
+├── assets/
+│   ├── css/
+│   │   └── admin.css              # Admin UI styles
+│   └── js/
+│       └── admin.js               # Admin UI scripts
+├── includes/
+│   ├── Activator.php              # Plugin activation
+│   ├── Deactivator.php            # Plugin deactivation
+│   ├── Plugin.php                 # Main plugin class
+│   ├── Admin/
+│   │   ├── Admin.php              # Admin functionality
+│   │   ├── Settings.php           # Settings page
+│   │   └── Assets.php             # Admin assets
+│   ├── Cache/
+│   │   ├── WPCache.php            # Core page cache
+│   │   ├── Purge.php              # Cache purge logic
+│   │   └── Preloader.php          # Cache preloading
+│   ├── Optimization/
+│   │   ├── CSS/
+│   │   │   ├── Minify.php         # CSS minification
+│   │   │   ├── Combine.php        # CSS combination
+│   │   │   └── CriticalCSS.php    # Critical CSS generation
+│   │   ├── JS/
+│   │   │   ├── Minify.php         # JS minification
+│   │   │   ├── Combine.php        # JS combination
+│   │   │   └── Defer.php          # JS defer/delay
+│   │   └── RemoveUnusedCSS.php    # RUCSS
+│   ├── Media/
+│   │   ├── Lazyload.php           # Image lazy loading
+│   │   ├── ImageFormat.php        # WebP/AVIF conversion
+│   │   └── ImageOptimize.php      # Image compression
+│   ├── Database/
+│   │   └── Optimizer.php          # Database cleanup
+│   └── Common/
+│       ├── FileSystem.php         # File system utilities
+│       ├──钩子/钩子.php           # Hook utilities
+│       └── HTTP.php               # HTTP utilities
+├── views/
+│   ├── admin-settings.php         # Settings page template
+│   └── admin-bar.php              # Admin bar menu
+└── languages/
+    └── wp-recache.pot             # Translation template
+```
+
+### Key Design Decisions
+
+1. **No vendor dependencies for core features.** Use WordPress built-in APIs wherever possible.
+2. **Modular architecture.** Each feature (cache, CSS, JS, images) is independent and can be disabled.
+3. **WordPress standards.** Follow WordPress coding standards and hook system.
+4. **Performance first.** Minimal overhead, no unnecessary database queries.
+
+## Implementation Strategy
+
+### Phase 1: Core Page Cache
+- Implement `advanced-cache.php` drop-in
+- Output buffering for HTML generation
+- Cache file management (create, serve, purge)
+- Admin settings page (basic)
+- Admin bar purge button
+
+### Phase 2: File Optimization
+- CSS minification
+- JS minification
+- CSS/JS combination
+- Defer/delay scripts
+- Critical CSS generation
+
+### Phase 3: Image Optimization
+- Lazy loading
+- WebP/AVIF conversion
+- Image compression
+- CLS prevention (width/height)
+
+### Phase 4: Advanced Features
+- Remove unused CSS
+- Database optimization
+- Preloading
+- CDN support
+
+## Legal Considerations
+
+1. **Document everything.** Keep records of the specification process.
+2. **Never access WP Rocket source** while implementing.
+3. **Use different naming.** Don't use "rocket" prefixes or similar naming.
+4. **Independent architecture.** Design your own class structure.
+5. **Different defaults.** Choose different default settings where possible.
+
+## Open Source Strategy
+
+1. **License:** GPL-2.0-or-later (same as WordPress)
+2. **Repository:** GitHub with public access
+3. **WordPress.org:** Submit to plugin directory
+4. **Community:** Accept contributions, maintain active development
+5. **Commercial model:** Open core with premium features or SaaS add-ons
+
+## Success Criteria
+
+1. Feature parity with WP Rocket for page cache, file optimization, image optimization
+2. No code overlap (verified by code review)
+3. Performance benchmarks comparable to or better than WP Rocket
+4. Clean, maintainable code following WordPress standards
+5. Active open source community