tauri-plugin-debug-tools 0.1.0

package/skills/debug-tauri/references/REFERENCE.md

@@ -0,0 +1,206 @@
+# Tauri WebView Debugger - Detailed Reference
+
+## Table of Contents
+- Tauri IPC command list
+- macOS screencapture commands
+- WebGPU Debug API (planned for Phase 4)
+- Process information
+- Troubleshooting
+- File path references
+- Reference links
+
+## Tauri IPC command list
+
+### capture_webview_state
+
+Get the WebView internal state as JSON.
+
+**TypeScript implementation:**
+```typescript
+import { captureWebViewState } from "@/lib/debugBridge";
+
+const state = await captureWebViewState();
+console.log(state);
+```
+
+**Response example:**
+```json
+{
+  "url": "http://localhost:5173",
+  "title": "iori",
+  "user_agent": "TauriWebView/2.0",
+  "viewport": {
+    "width": 1200,
+    "height": 800
+  }
+}
+```
+
+### get_console_logs
+
+Get console logs (currently returns an empty array).
+
+**Future implementation:**
+Hook `console.log` and similar calls on the frontend and send as Tauri events.
+
+### send_debug_command
+
+Send a debug command to the WebView (event-based).
+
+**Example:**
+```typescript
+import { sendDebugCommand } from "@/lib/debugBridge";
+
+await sendDebugCommand("get_gpu_state", { includeBuffers: true });
+```
+
+### take_screenshot
+
+Request a screenshot (system command recommended).
+
+**Error message:**
+```
+Use system screencapture command instead.
+Run: screencapture -x -T 0 /tmp/tauri_screenshot.png
+```
+
+## macOS screencapture commands
+
+### Full screen capture
+
+```bash
+screencapture -x -T 0 /tmp/screenshot.png
+```
+
+**Options:**
+- `-x`: Disable sound
+- `-T <seconds>`: Delay (0 = immediate)
+
+### Window selection (interactive)
+
+```bash
+screencapture -w /tmp/window_screenshot.png
+```
+
+The user clicks a window to select it.
+
+### Specify a window ID for a specific process
+
+```bash
+# Get the window ID
+osascript -e 'tell application "System Events" to get unix id of first process whose name is "<app-binary-name>"'
+
+# Capture using that ID
+screencapture -l <window-id> /tmp/tauri_window.png
+```
+
+## WebGPU Debug API (planned for Phase 4)
+
+### captureWebGPUState()
+
+Capture WebGPU state comprehensively.
+
+**Return value:**
+```typescript
+{
+  deviceInfo: GPUAdapterInfo,
+  bufferStats: {
+    particleBuffer: { size: number, usage: number },
+    uniformBuffer: { size: number, usage: number },
+  },
+  computeResults: Float32Array,
+  performanceMetrics: {
+    fps: number,
+    frameTime: number,
+    memoryUsage: number
+  }
+}
+```
+
+### getDeviceInfo()
+
+Get GPU device information.
+
+```typescript
+const info = await getDeviceInfo();
+// { vendor: "Apple", architecture: "..." }
+```
+
+### exportComputeResults()
+
+Export compute shader results to the CPU.
+
+```typescript
+const results = await exportComputeResults();
+// Float32Array(100000) - particle position data
+```
+
+### getPerformanceMetrics()
+
+Get performance metrics.
+
+```typescript
+const metrics = await getPerformanceMetrics();
+// { fps: 60, frameTime: 16.67, memoryUsage: 197 }
+```
+
+## Process information
+
+### Check running Tauri processes
+
+```bash
+ps aux | grep <app-binary-name> | grep -v grep
+```
+
+**Example output:**
+```
+user  94678  1.6  0.3  440546784  197920 s011  S+   11:47AM   0:12.85 target/debug/<app-binary-name>
+```
+
+### Process details
+
+```bash
+ps -p 94678 -o pid,vsz,rss,%cpu,%mem,command
+```
+
+## Troubleshooting
+
+### Error: "Main window not found"
+
+**Cause**: The main window is not running or the label differs.
+
+**Fix:**
+1. Ensure the app is running (e.g. `tauri dev`)
+2. Ensure `tauri.conf.json` has `windows.label` set to "main"
+
+### Error: "Process not found"
+
+**Cause**: The target process is not running.
+
+**Fix:**
+```bash
+# Example: from the project root
+tauri dev
+```
+
+### Screenshot cannot be captured
+
+**Cause**: Screen recording is not allowed in macOS privacy settings.
+
+**Fix:**
+1. System Settings > Privacy & Security > Screen Recording
+2. Select Screen Recording
+3. Add Terminal (or the launcher) to the allowed list
+
+## File path references
+
+### Reference (optional)
+
+- If there is a debug command implementation such as `src-tauri/src/commands/debug.rs`, you can collect logs with `append_debug_logs` and similar commands.
+- If you provide a frontend bridge like `src/lib/debugBridge.ts`, it becomes easier to fetch state via IPC.
+
+## Reference links
+
+- [Tauri IPC Commands](https://v2.tauri.app/develop/calling-rust/)
+- [Claude Code Skills Documentation](https://code.claude.com/docs/ja/skills)
+- [macOS screencapture man page](https://ss64.com/osx/screencapture.html)

package/skills/debug-tauri/references/REPORT_TEMPLATE.md

@@ -0,0 +1,166 @@
+# Debug Report Template
+
+Use this exact structure for consistency:
+
+````markdown
+# Tauri Debug Report - [YYYY-MM-DD HH:MM]
+
+## Screenshot
+
+![Screenshot](/tmp/tauri_debug_TIMESTAMP.png)
+
+## Process Status
+
+- Status: [Running/Not Running]
+- PID: [pid]
+- Memory (RSS): [MB]
+- CPU: [percentage]%
+- Command: [command line]
+
+## Console Logs
+
+### Error Count: [N]
+
+### Warning Count: [N]
+
+### Recent Errors
+
+```
+[error logs from last 5 entries]
+```
+
+### Recent Warnings
+
+```
+[warning logs from last 5 entries]
+```
+
+### Log Statistics
+
+- Total logs: [N]
+- Errors: [N]
+- Warnings: [N]
+- Info: [N]
+- Debug: [N]
+
+## WebView State
+
+```json
+{
+  "url": "...",
+  "title": "...",
+  "user_agent": "...",
+  "viewport": {
+    "width": ...,
+    "height": ...
+  }
+}
+```
+
+## Visual Analysis
+
+### UI State
+
+[Description of visible UI elements, current screen, navigation state]
+
+### Identified Issues
+
+- [ ] Issue 1: [description with location/screenshot reference]
+- [ ] Issue 2: [description with location/screenshot reference]
+- [ ] Issue 3: [description with location/screenshot reference]
+
+### Layout Problems
+
+[Any layout issues, misalignments, overflow, or rendering problems]
+
+### Error Indicators
+
+[Visible error messages, banners, toast notifications, console output]
+
+## Performance Analysis
+
+### Memory Usage
+
+- RSS: [MB]
+- VSZ: [MB]
+- Trend: [increasing/stable/decreasing]
+
+### CPU Usage
+
+- Current: [%]
+- Average: [%]
+- Spikes: [yes/no, describe if yes]
+
+### Rendering
+
+- FPS: [if available]
+- Frame drops: [yes/no]
+- GPU usage: [if available]
+
+## Root Cause Analysis
+
+### Primary Cause
+
+[Analysis based on collected evidence from logs, screenshots, and state]
+
+### Contributing Factors
+
+1. [Factor 1]
+2. [Factor 2]
+3. [Factor 3]
+
+### Evidence
+
+- Log evidence: [specific errors/warnings]
+- Visual evidence: [screenshot observations]
+- State evidence: [WebView state anomalies]
+
+## Recommendations
+
+### Immediate Actions
+
+1. **[Action 1]**
+   - Implementation: [specific code changes or commands]
+   - Expected outcome: [what should change]
+   - Risk: [low/medium/high]
+
+2. **[Action 2]**
+   - Implementation: [specific code changes or commands]
+   - Expected outcome: [what should change]
+   - Risk: [low/medium/high]
+
+### Long-term Improvements
+
+1. [Improvement 1 with rationale]
+2. [Improvement 2 with rationale]
+3. [Improvement 3 with rationale]
+
+## Next Steps
+
+- [ ] Implement fix for [specific issue]
+- [ ] Test in [environment/scenario]
+- [ ] Monitor [specific metric/behavior]
+- [ ] Document changes in [location]
+- [ ] Verify fix with [validation method]
+
+## Additional Notes
+
+[Any other observations, edge cases, or relevant context]
+
+---
+
+**Report generated by**: [Your name/automated tool]
+**Review status**: [Pending/Reviewed/Implemented]
+````
+
+## Usage Tips
+
+1. **Fill sections progressively** as you complete each debug workflow step
+2. **Be specific** in root cause analysis - avoid vague statements
+3. **Include evidence** - reference specific log lines, screenshot areas
+4. **Actionable recommendations** - provide exact commands or code changes
+5. **Track progress** - check off items as you implement fixes
+
+## Example Report
+
+See `examples/sample_debug_report.md` (if created) for a filled example.

package/skills/debug-tauri/references/SCREENSHOTS.md

@@ -0,0 +1,193 @@
+# Screenshot Capture Reference
+
+## Official Plugin (Recommended)
+
+Use `tauri-plugin-screenshots` for cross-platform screenshot capture.
+
+### Quick Start
+
+```typescript
+import { captureMainWindow } from "tauri-plugin-debug-tools/screenshotHelper";
+
+// Capture main window as base64 PNG
+const screenshot = await captureMainWindow();
+if (screenshot) {
+  console.log("Screenshot captured successfully");
+}
+```
+
+### Available Methods
+
+#### captureMainWindow()
+
+Captures the first available window.
+
+```typescript
+import { captureMainWindow } from "tauri-plugin-debug-tools/screenshotHelper";
+
+const imagePath = await captureMainWindow();
+```
+
+**Returns**: `string | null` - Base64 PNG data or null if no windows
+
+#### captureAllWindows()
+
+Captures all application windows.
+
+```typescript
+import { captureAllWindows } from "tauri-plugin-debug-tools/screenshotHelper";
+
+const screenshots = await captureAllWindows();
+```
+
+**Returns**: `string[]` - Array of base64 PNG data
+
+#### capturePrimaryMonitor()
+
+Captures the primary display.
+
+```typescript
+import { capturePrimaryMonitor } from "tauri-plugin-debug-tools/screenshotHelper";
+
+const monitorScreenshot = await capturePrimaryMonitor();
+```
+
+**Returns**: `string | null` - Base64 PNG data or null if no monitors
+
+### Advanced Usage
+
+```typescript
+import {
+  getScreenshotableWindows,
+  getWindowScreenshot,
+  getScreenshotableMonitors,
+  getMonitorScreenshot,
+} from "tauri-plugin-screenshots-api";
+
+// List available windows
+const windows = await getScreenshotableWindows();
+console.log(windows); // [{ id: 1, title: "My App" }, ...]
+
+// Capture specific window
+const screenshot = await getWindowScreenshot(windows[0].id);
+
+// List available monitors
+const monitors = await getScreenshotableMonitors();
+
+// Capture specific monitor
+const monitorShot = await getMonitorScreenshot(monitors[0].id);
+```
+
+### Platform Support
+
+- ✅ **macOS**: Full support
+- ✅ **Windows**: Full support
+- ✅ **Linux**: Full support (X11/Wayland)
+
+### Permissions
+
+Add to app capabilities:
+
+```json
+{
+  "permissions": ["screenshots:default"]
+}
+```
+
+## Legacy: macOS screencapture Command
+
+### Full Screen Capture
+
+```bash
+screencapture -x -T 0 /tmp/screenshot.png
+```
+
+**Options:**
+
+- `-x`: Disable sound
+- `-T <seconds>`: Delay time (0 = execute immediately)
+
+### Window Selection (Interactive)
+
+```bash
+screencapture -w /tmp/window_screenshot.png
+```
+
+User clicks to select the window.
+
+### Specific Process Window by ID
+
+```bash
+# Get window ID
+osascript -e 'tell application "System Events" to get unix id of first process whose name is "<app-binary-name>"'
+
+# Capture by ID
+screencapture -l <window-id> /tmp/tauri_window.png
+```
+
+### Automated Capture (Legacy)
+
+**Deprecated**: Use official plugin API instead.
+
+Legacy script for macOS only:
+
+```bash
+TAURI_APP_NAME=<your-app> scripts/capture.sh
+```
+
+This script:
+
+1. Verifies the app is running
+2. Captures a timestamped screenshot
+3. Returns the screenshot path
+
+**Migration**: Replace with `captureMainWindow()` from plugin API for cross-platform support.
+
+## Troubleshooting
+
+### Error: Screenshot Not Captured
+
+**Cause**: macOS privacy settings deny screen recording permission.
+
+**Solution:**
+
+1. System Preferences > Security & Privacy > Privacy
+2. Select "Screen Recording"
+3. Add Terminal (or execution source) to allowed list
+
+### Permission Check
+
+Run validation script:
+
+```bash
+scripts/validate_setup.sh
+```
+
+This checks screen recording permissions and other debug requirements.
+
+## Legacy: Platform-Specific CLI Tools
+
+**Deprecated**: Use official plugin API for unified cross-platform support.
+
+### Linux (Legacy)
+
+```bash
+# Using scrot
+scrot /tmp/screenshot.png
+
+# Using gnome-screenshot
+gnome-screenshot -f /tmp/screenshot.png
+```
+
+### Windows (Legacy)
+
+```powershell
+# Using PowerShell
+Add-Type -AssemblyName System.Windows.Forms
+[System.Windows.Forms.SendKeys]::SendWait("{PRTSC}")
+```
+
+## References
+
+- [tauri-plugin-screenshots Repository](https://github.com/ayangweb/tauri-plugin-screenshots)
+- [macOS screencapture man page](https://ss64.com/osx/screencapture.html) (legacy)

package/skills/debug-tauri/references/TROUBLESHOOTING.md

@@ -0,0 +1,144 @@
+# Troubleshooting Guide
+
+## Common Errors
+
+### "Main window not found"
+
+**Cause**: Main window is not launched or has different label name.
+
+**Solution:**
+
+1. Verify app is running: `ps aux | grep <app-binary-name>`
+2. Check `tauri.conf.json` has `windows.label` set to "main"
+3. Start app if not running: `tauri dev`
+
+### "Process not found"
+
+**Cause**: Target process is not running.
+
+**Solution:**
+
+```bash
+# Start app from project root
+tauri dev
+
+# Or for production build
+./target/release/<app-binary-name>
+```
+
+**Verify process:**
+
+```bash
+TAURI_APP_NAME=<your-app> scripts/capture.sh
+```
+
+### Screenshot Capture Fails
+
+**Cause**: macOS privacy settings deny screen recording.
+
+**Solution:**
+
+1. System Preferences > Security & Privacy > Privacy
+2. Select "Screen Recording"
+3. Add Terminal (or IDE) to allowed list
+4. Restart terminal/IDE
+
+**Quick check:**
+
+```bash
+scripts/validate_setup.sh
+```
+
+### Console Logs Empty
+
+**Cause**: Frontend logger not initialized or logs not being captured.
+
+**Solutions:**
+
+**Option 1**: Ensure frontend logger is initialized
+
+```typescript
+import { initConsoleLogger } from "tauri-plugin-debug-tools/consoleLogger";
+
+initConsoleLogger();
+```
+
+**Option 2**: Check log file exists
+
+```bash
+ls -lh /tmp/tauri_console_logs.jsonl
+```
+
+**Option 3**: Use IPC method
+
+```typescript
+const logs = await invoke("plugin:debug-tools|get_console_logs");
+```
+
+### WebView State Returns Null
+
+**Cause**: WebView not fully initialized or permissions issue.
+
+**Solutions:**
+
+1. Wait for WebView ready event
+2. Verify debug permissions in `capabilities/default.json`
+3. Check Tauri version compatibility (requires v2.0+)
+
+### Permission Denied Errors
+
+**Cause**: Missing debug permissions in app capabilities.
+
+**Solution:**
+
+Add to `src-tauri/capabilities/default.json`:
+
+```json
+{
+  "permissions": [
+    "debug-tools:allow-capture-webview-state",
+    "debug-tools:allow-get-console-logs",
+    "debug-tools:allow-send-debug-command"
+  ]
+}
+```
+
+## Validation Checklist
+
+Run this before debugging:
+
+```bash
+scripts/validate_setup.sh
+```
+
+Manual checks:
+
+- [ ] App is running (verify with `ps aux | grep <app-name>`)
+- [ ] Screen recording permission granted (macOS)
+- [ ] Debug permissions enabled in capabilities
+- [ ] Frontend logger initialized (if using log collection)
+- [ ] Tauri version >= 2.0
+
+## Getting Help
+
+If issues persist:
+
+1. Check plugin version compatibility
+2. Review Tauri logs: `tauri dev --verbose`
+3. Validate setup: `scripts/validate_setup.sh`
+4. Consult [Tauri documentation](https://v2.tauri.app)
+
+## File Path References
+
+**Debug command implementation:**
+
+- `src-tauri/src/commands/debug.rs` (if exists)
+
+**Frontend bridge:**
+
+- `src/lib/debugBridge.ts` (recommended location)
+
+**Log output:**
+
+- `/tmp/tauri_console_logs.jsonl` (default)
+- `/tmp/tauri_debug_*.png` (screenshots)