docs: Update CLAUDE.md with memory leak investigation session

- Documented v0.4.1 through v0.4.9 fix attempts - Listed all protection mechanisms in place - Recorded key learnings about WordPress hooks and recursion - Status: unresolved, documented as known incompatibility Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
docs: Add known plugin incompatibilities section
2026-02-02 20:10:09 +01:00 · 2026-02-02 20:07:50 +01:00
2 changed files with 68 additions and 1 deletions
@@ -552,3 +552,58 @@ wp-fedistream/
 - Uses Gitea API directly for release creation (not GitHub Actions)
 - Submodule uses relative URL for CI compatibility
 - Composer symlinks from `lib/wc-licensed-product-client` to vendor
+
+### 2026-02-02 - Memory Leak Investigation v0.4.1 through v0.4.9
+
+**Summary:** Investigated memory exhaustion issue when WP FediStream is used with WP Prometheus plugin. Multiple fix attempts were made but the root cause remains unresolved.
+
+**Problem:**
+
+- PHP Fatal error: Allowed memory size exhausted (1GB)
+- Error locations varied: Twig StagingExtension.php, Environment.php, ExtensionSet.php, WordPress class-wp-hook.php
+- Only occurs when WP Prometheus plugin is also active
+- Suspected infinite recursion through WordPress hook system
+
+**Fix Attempts (v0.4.1 - v0.4.8):**
+
+1. **v0.4.1** - Added recursion depth tracking in `get_post_data()`, skip `the_content` filter at depth > 1
+2. **v0.4.2** - Added `$in_shortcode_context` flag, all shortcode render methods enter context before data loading
+3. **v0.4.3** - Changed boolean to counter (`$shortcode_context_depth`), added context to `template-wrapper.php`
+4. **v0.4.4** - Fixed `get_the_excerpt()` which internally triggers `the_content` filter
+5. **v0.4.5** - Added render depth tracking in `Plugin::render()`, strip shortcodes from content
+6. **v0.4.6** - Added `$loading_page_template` flag to block shortcode rendering during page template loading
+7. **v0.4.7** - Added `$rendering_main_template` hard lock in `Plugin::render()`, reduced MAX_RENDER_DEPTH to 2
+8. **v0.4.8** - Nuclear option: ALWAYS skip `the_content` filter (didn't work, reverted)
+
+**v0.4.9 - Current State:**
+
+- Reverted nuclear option
+- Kept all other protections in place
+- Issue documented in README.md as known incompatibility
+
+**Files Modified:**
+
+- `includes/Frontend/TemplateLoader.php` - Multiple recursion protection mechanisms
+- `includes/Frontend/Shortcodes.php` - Shortcode context entry, page template loading check
+- `includes/Frontend/template-wrapper.php` - Page template loading flag, main template render flag
+- `includes/Plugin.php` - Render depth tracking, main template rendering lock
+- `README.md` - Added Known Issues section
+
+**Protection Mechanisms in Place:**
+
+1. `$recursion_depth` counter in `get_post_data()` (max 3)
+2. `$shortcode_context_depth` counter for nested shortcodes
+3. `$loading_page_template` flag blocks shortcode rendering during page load
+4. `$rendering_main_template` flag in `Plugin::render()` blocks parallel renders
+5. `MAX_RENDER_DEPTH = 2` in `Plugin::render()`
+6. Skip `the_content` and `get_the_excerpt()` when in protected context
+7. Strip shortcodes from content when skipping content filter
+
+**Key Learnings:**
+
+- `get_the_excerpt()` internally calls `apply_filters('the_content', ...)` when generating auto-excerpts
+- `the_content` filter triggers `do_shortcode()` which can cause recursive shortcode processing
+- WordPress hook system (class-wp-hook.php) can itself be the recursion point
+- The interaction between FediStream and WP Prometheus appears to be at a fundamental WordPress level
+
+**Status:** UNRESOLVED - Documented as known incompatibility, investigation to continue later
@@ -2,7 +2,7 @@

 Stream music over ActivityPub - Build your own music streaming platform for Musicians and Labels.

-[![Version](https://img.shields.io/badge/version-0.4.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.4.9-blue.svg)](CHANGELOG.md)
 [![PHP](https://img.shields.io/badge/PHP-%3E%3D8.3-purple.svg)](https://php.net)
 [![WordPress](https://img.shields.io/badge/WordPress-%3E%3D6.4-blue.svg)](https://wordpress.org)
 [![License](https://img.shields.io/badge/license-GPL--2.0%2B-green.svg)](https://www.gnu.org/licenses/gpl-2.0.html)
@@ -39,6 +39,18 @@ WP FediStream is a WordPress plugin that enables musicians, bands, and labels to
 - [ActivityPub Plugin](https://wordpress.org/plugins/activitypub/) - For Fediverse integration
 - [WooCommerce](https://woocommerce.com/) 10.0+ - For selling music

+## Known Issues
+
+### Plugin Incompatibilities
+
+The following plugins are known to cause issues when used together with WP FediStream:
+
+| Plugin        | Issue                                                             | Status              |
+|---------------|-------------------------------------------------------------------|---------------------|
+| WP Prometheus | Memory exhaustion (PHP Fatal error) when viewing FediStream pages | Under investigation |
+
+If you encounter memory issues or PHP fatal errors, try deactivating these plugins temporarily to isolate the problem.
+
 ## License Key

 WP FediStream requires a valid license key for frontend functionality (player, shortcodes, ActivityPub). The admin dashboard works without a license, allowing you to configure the plugin before activation.