update SYNC.md — grant full debug/fix permission for GUI issue

SYNC.md

@@ -1,64 +1,108 @@
 # PluginBridge — Sync File
-> HF Claude builds. Claude Code: pull → build → paste error (if any). That's it.
 
 ---
 
-## Claude Code Rules (TOKEN EFFICIENT MODE)
+## MODE: FULL DEBUG (active until GUI works)
+
+You have FULL permission to:
+- Read all source files
+- Add DBG prints
+- Write code
+- Fix bugs
+- Push to this HF repo
+
+**Do NOT just build. Debug and fix.**
+
+---
+
+## THE PROBLEM
+
+Plugin loads successfully (name + param count shows in top bar) but **GUI does not appear** inside PluginBridge's editor.
+
+## ARCHITECTURE (v0.4)
 
-**Your ENTIRE job is these commands:**
-```bash
-cd ~/pluginbridge && git pull
-rm -rf build && mkdir build && cd build
-cmake .. -DCMAKE_C_COMPILER=/usr/bin/cc -DCMAKE_CXX_COMPILER=/usr/bin/c++
-cmake --build . --config Release 2>&1 | tail -40
 ```
+PluginBridge.vst3 (inside Ableton)
+├── PluginBridgeProcessor.cpp — spawns Helper, shared memory audio, IPC
+├── PluginBridgeEditor.mm — should display CARemoteLayerClient layer
+├── HelperConnection.cpp — Unix socket IPC to Helper
+├── McpServer.cpp — HTTP MCP on port 16620
+└── Blocklist.h — persistent blocklist
 
-NOTE: Full clean rebuild needed — architecture changed from v0.3 (in-process) to v0.4 (out-of-process with CARemoteLayerServer).
+PluginBridgeHelper.app (separate crash-safe process)
+├── main.cpp — JUCE app, --pid argument
+├── HelperPluginHost.mm — loads plugin, audio, CARemoteLayerServer GUI
+├── HelperIPC.cpp — receives commands, sends notifications
+└── SharedAudioBuffer.h — shared memory
+```
 
-**If build succeeds:** Reply "✅ build ok" — nothing else.
+## THE CHAIN THAT SHOULD HAPPEN
 
-**If build fails:** Reply with ONLY the first 3 errors:
 ```
-❌ [filename]:[line] — [one-line error message]
+1. User selects plugin → Processor::loadPlugin() → Helper loads it ✅ WORKS
+2. Processor::onPluginLoaded fires → Editor calls showPluginGui()
+3. showPluginGui() → sends {"cmd":"show_gui"} to Helper
+4. Helper HelperPluginHost::showGui() →
+   - Creates plugin editor (NSView)
+   - Creates hidden NSWindow (layer-backed)
+   - Sets up CARemoteLayerServer
+   - Registers Mach port via NSMachBootstrapServer
+   - Calls onGuiCreated callback
+5. onGuiCreated → HelperIPC::sendGuiReady(portName, width, height)
+6. HelperConnection receives {"notify":"gui_ready",...} → calls onGuiReady
+7. Processor stores remoteLayerPortName + size → triggers Editor onGuiReady
+8. Editor::connectRemoteLayer() →
+   - Looks up Mach port via NSMachBootstrapServer
+   - Creates CARemoteLayerClient with port
+   - Adds client.layer to JUCE NSView
+   - Resizes editor to fit
 ```
 
-## DO NOT:
-- Explain errors
-- Suggest fixes
-- Write code
-- Add commentary
+**Something in steps 2-8 is failing silently.**
+
+## HOW TO DEBUG
 
-## Architecture (v0.4 — CARemoteLayerServer)
+1. Check Ableton log:
+```bash
+grep -i "pluginbridge\|helper\|GUI\|layer\|port\|gui_ready" ~/Library/Preferences/Ableton/Live\ 12.4/Log.txt | tail -50
+```
 
+2. Check if Helper process is running:
+```bash
+ps aux | grep PluginBridgeHelper
 ```
-PluginBridge.vst3 (inside Ableton):
-├── PluginBridgeProcessor (audio via shared memory)
-├── PluginBridgeEditor.mm (displays CARemoteLayerClient layer — plugin GUI inside Ableton window)
-├── HelperConnection (spawns helper, IPC, shared mem)
-├── McpServer (port 16620)
-└── Blocklist (~/Library/PluginBridge/blocklist.txt)
-
-PluginBridgeHelper.app (separate process, crash-safe):
-├── main.cpp (JUCE app, --pid argument)
-├── HelperPluginHost.mm (loads plugin, audio, CARemoteLayerServer for GUI)
-├── HelperIPC.cpp (commands + mouse/key event forwarding)
-└── SharedAudioBuffer.h (shared memory audio bridge)
+
+3. Add DBG() prints at each step in the chain to find where it breaks.
+
+4. Possible failure points:
+   - `showPluginGui()` never called (step 2)
+   - `show_gui` command never reaches Helper (step 3)
+   - `showGui()` fails silently — editor not created, or CARemoteLayerServer init fails (step 4)
+   - Mach port registration fails (NSMachBootstrapServer may be deprecated/broken on modern macOS)
+   - `gui_ready` notification never sent or never received (steps 5-6)
+   - `connectRemoteLayer()` fails — port lookup returns nil (step 8)
+   - `CARemoteLayerClient initWithServerPort:` fails or layer is empty
+
+5. **Key question:** Does `CARemoteLayerServer` / `CARemoteLayerClient` actually work on macOS 14+ Sonoma/Sequoia? The API exists but may not function as documented for cross-process layer sharing without App Groups or XPC. If it doesn't work, we need a different approach (IOSurface or pixel copy).
+
+## KEY FILES
+
+| File | Role |
+|---|---|
+| `Source/Plugin/PluginBridgeEditor.mm` | `connectRemoteLayer()` — CARemoteLayerClient side |
+| `Source/Helper/HelperPluginHost.mm` | `showGui()` — CARemoteLayerServer side |
+| `Source/Helper/HelperIPC.cpp` | Wires `onGuiCreated` → `sendGuiReady()` |
+| `Source/Plugin/HelperConnection.cpp` | `handleNotification()` receives `gui_ready` |
+| `Source/Plugin/PluginBridgeProcessor.cpp` | `onGuiReady` callback stores port name |
+
+## BUILD
+
+```bash
+cd ~/pluginbridge && git pull
+cd build && cmake --build . --config Release 2>&1 | tail -30
 ```
 
-**How GUI works:**
-1. Helper loads plugin → creates editor → renders into CARemoteLayerServer
-2. Helper registers Mach port via NSMachBootstrapServer (named per PID)
-3. Helper sends "gui_ready" notification with port name + size to host
-4. PluginBridge.vst3 looks up Mach port → creates CARemoteLayerClient
-5. Adds client.layer as sublayer of JUCE editor's NSView
-6. Plugin GUI appears INSIDE Ableton's plugin window (no separate window)
-7. Mouse/keyboard events forwarded from host → helper via IPC
-
-**Crash safety:** Plugin crashes kill only the Helper. Ableton survives.
-**Fullscreen:** CALayer is part of the view hierarchy — follows into fullscreen.
-
-## Status
-**Last push:** 2026-05-17 — v0.4 complete rewrite (CARemoteLayerServer architecture)
-**Build:** Needs clean rebuild (rm -rf build)
-**Test:** Restart Ableton → load PluginBridge → select Pro-Q 4 → GUI should appear inside PluginBridge's editor (no floating window). Then test Kickstart 2 → should NOT crash Ableton (Helper crashes, gets blocklisted).
-**Also clear blocklist:** `rm -f ~/Library/PluginBridge/blocklist.txt`
+## AFTER FIXING
+
+Push all changes to: https://huggingface.co/RAM2118/pluginbridge
+Update this SYNC.md with what you fixed and current status.