docs: add frontend console debugging guide and mermaid syntax standards

docs/development/frontend-console-debugging.md

@@ -0,0 +1,150 @@
+# 🛠️ Debugging Python Plugins with Frontend Console
+
+When developing plugins for Open WebUI, debugging can be challenging. Standard `print()` statements or server-side logging might not always be accessible, especially in hosted environments or when you want to see the data flow in real-time alongside the UI interactions.
+
+This guide introduces a powerful technique: **Frontend Console Debugging**. By injecting JavaScript from your Python plugin, you can print structured logs directly to the browser's Developer Tools console (F12).
+
+## Why Frontend Debugging?
+
+*   **Real-time Feedback**: See logs immediately as actions happen in the browser.
+*   **Rich Objects**: Inspect complex JSON objects (like `body` or `messages`) interactively, rather than reading massive text dumps.
+*   **No Server Access Needed**: Debug issues even if you don't have SSH/Console access to the backend server.
+*   **Clean Output**: Group logs using `console.group()` to keep your console organized.
+
+## The Core Mechanism
+
+Open WebUI plugins (both Actions and Filters) support an event system. We can leverage the `__event_call__` (or sometimes `__event_emitter__`) to send a special event of type `execute`. This tells the frontend to run the provided JavaScript code.
+
+### The Helper Method
+
+To make this easy to use, we recommend adding a helper method `_emit_debug_log` to your plugin class.
+
+```python
+import json
+from typing import List
+
+async def _emit_debug_log(
+    self, 
+    __event_call__, 
+    title: str, 
+    data: dict
+):
+    """
+    Emit debug log to browser console via JS execution.
+    
+    Args:
+        __event_call__: The event callable passed to action/outlet.
+        title: A title for the log group.
+        data: A dictionary of data to log.
+    """
+    # 1. Check if debugging is enabled (recommended)
+    if not getattr(self.valves, "show_debug_log", True) or not __event_call__:
+        return
+
+    try:
+        # 2. Construct the JavaScript code
+        # We use an async IIFE (Immediately Invoked Function Expression) 
+        # to ensure a clean scope and support await if needed.
+        js_code = f"""
+            (async function() {{
+                console.group("🛠️ Plugin Debug: {title}");
+                console.log({json.dumps(data, ensure_ascii=False)});
+                console.groupEnd();
+            }})();
+        """
+
+        # 3. Send the execute event
+        await __event_call__(
+            {
+                "type": "execute",
+                "data": {"code": js_code},
+            }
+        )
+    except Exception as e:
+        print(f"Error emitting debug log: {e}")
+```
+
+## Implementation Steps
+
+### 1. Add a Valve for Control
+
+It's best practice to make debugging optional so it doesn't clutter the console for normal users.
+
+```python
+from pydantic import BaseModel, Field
+
+class Filter:
+    class Valves(BaseModel):
+        show_debug_log: bool = Field(
+            default=False, 
+            description="Print debug logs to browser console (F12)"
+        )
+    
+    def __init__(self):
+        self.valves = self.Valves()
+```
+
+### 2. Inject `__event_call__`
+
+Ensure your `action` (for Actions) or `outlet` (for Filters) method accepts `__event_call__`.
+
+**For Filters (`outlet`):**
+
+```python
+async def outlet(
+    self,
+    body: dict,
+    __user__: Optional[dict] = None,
+    __event_call__=None,  # <--- Add this
+    __metadata__: Optional[dict] = None,
+) -> dict:
+```
+
+**For Actions (`action`):**
+
+```python
+async def action(
+    self,
+    body: dict,
+    __user__=None,
+    __event_call__=None, # <--- Add this
+    __request__=None,
+):
+```
+
+### 3. Call the Helper
+
+Now you can log anything, anywhere in your logic!
+
+```python
+# Inside your logic...
+new_content = self.process_content(content)
+
+# Log the before and after
+await self._emit_debug_log(
+    __event_call__,
+    "Content Normalization",
+    {
+        "original": content,
+        "processed": new_content,
+        "changes": diff_list
+    }
+)
+```
+
+## Best Practices
+
+1.  **Use `json.dumps`**: Always serialize your Python dictionaries to JSON strings before embedding them in the f-string. This handles escaping quotes and special characters correctly.
+2.  **Async IIFE**: Wrapping your JS in `(async function() { ... })();` is safer than raw code. It prevents variable collisions with other scripts and allows using `await` inside your debug script if you ever need to check DOM elements.
+3.  **Check for None**: Always check if `__event_call__` is not None before using it, as it might not be available in all contexts (e.g., when running tests or in older Open WebUI versions).
+
+## Example Output
+
+When enabled, your browser console will show:
+
+```text
+> 🛠️ Plugin Debug: Content Normalization
+  > {original: "...", processed: "...", changes: [...]}
+```
+
+You can expand the object to inspect every detail of your data. Happy debugging!