fix: replace CARemoteLayerServer with CAContext+CALayerHost for cross-process GUI

Three bugs killed the GUI:
1. CARemoteLayerServer does not capture a hidden NSWindow's content cross-process.
Replaced with CAContext (server) + CALayerHost (client) — the correct private-but-stable
macOS API for cross-process layer embedding, stable from 10.10 through Sequoia.
2. NSWindow was never orderFront: — WindowServer never composited its content.
Fixed: window positioned at (-32000,-32000) and orderFront: called.
3. NSMachBootstrapServer (deprecated on 13+) no longer needed.
contextId (uint32_t) is sent directly over the existing IPC socket.

New file: Source/Shared/PrivateCA.h — declares CAContext, CALayerHost, CGSMainConnectionID.

SYNC.md

@@ -2,107 +2,90 @@
 
 ---
 
-## MODE: FULL DEBUG (active until GUI works)
+## STATUS: v0.4.1 — GUI fix pushed (2026-05-17)
 
-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.**
+Build: ✅ Clean  
+GUI: Awaiting first real test in Ableton
 
 ---
 
-## THE PROBLEM
+## WHAT WAS FIXED
+
+### Root cause: Wrong cross-process layer API + invisible window
+
+Three bugs in the original v0.4 GUI approach:
+
+**Bug 1 — Wrong API (main bug):**  
+`CARemoteLayerServer` + `NSMachBootstrapServer` does NOT share a hidden NSWindow's content to another process. The correct private-but-stable API is:
+- **Helper (server):** `CAContext contextWithCGSConnection:options:` — wraps a `CALayer` and exposes it as a `uint32_t contextId`
+- **Host (client):** `CALayerHost.contextId = contextId` — a `CALayer` subclass that renders the remote context inline
 
-Plugin loads successfully (name + param count shows in top bar) but **GUI does not appear** inside PluginBridge's editor.
+**Bug 2 — NSWindow never visible:**  
+The window was created but `orderFront:` was never called. Even if CARemoteLayerServer had worked, the WindowServer wouldn't composite a window that isn't ordered front. Fix: window is positioned off-screen at `(-32000, -32000)` and `orderFront:` is called.
 
-## ARCHITECTURE (v0.4)
+**Bug 3 — NSMachBootstrapServer deprecated:**  
+Not needed anymore. The `contextId` (uint32_t) is sent directly over the existing IPC socket as the `layerPortName` string field (decimal number). No Mach port bootstrapping required.
+
+### Files changed
+| File | What changed |
+|---|---|
+| `Source/Shared/PrivateCA.h` | **New** — declares `CAContext`, `CALayerHost`, `CGSMainConnectionID` |
+| `Source/Helper/HelperPluginHost.h` | `remoteLayerServer` → `caContext` |
+| `Source/Helper/HelperPluginHost.mm` | `showGui()` uses `CAContext`; `hideGui()` releases properly; window `orderFront:`  |
+| `Source/Plugin/PluginBridgeEditor.mm` | `connectRemoteLayer()` uses `CALayerHost`; no Mach port lookup |
+
+---
+
+## ARCHITECTURE (v0.4.1)
 
 ```
 PluginBridge.vst3 (inside Ableton)
 ├── PluginBridgeProcessor.cpp — spawns Helper, shared memory audio, IPC
-├── PluginBridgeEditor.mm — should display CARemoteLayerClient layer
+├── PluginBridgeEditor.mm — displays CALayerHost (contextId from Helper)
 ├── HelperConnection.cpp — Unix socket IPC to Helper
 ├── McpServer.cpp — HTTP MCP on port 16620
 └── Blocklist.h — persistent blocklist
 
 PluginBridgeHelper.app (separate crash-safe process)
 ├── main.cpp — JUCE app, --pid argument
-├── HelperPluginHost.mm — loads plugin, audio, CARemoteLayerServer GUI
+├── HelperPluginHost.mm — loads plugin, CAContext GUI server
 ├── HelperIPC.cpp — receives commands, sends notifications
 └── SharedAudioBuffer.h — shared memory
 ```
 
-## THE CHAIN THAT SHOULD HAPPEN
-
-```
-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
-```
-
-**Something in steps 2-8 is failing silently.**
+**How GUI works (v0.4.1):**
+1. Helper loads plugin → creates editor → embeds NSView in off-screen NSWindow
+2. NSWindow ordered front at (-32000, -32000) — invisible to user, visible to compositor
+3. `CAContext.layer = window.contentView.layer` — exposes the layer tree cross-process
+4. Helper sends `contextId` (uint32_t as decimal string) via `gui_ready` IPC notification
+5. Host creates `CALayerHost(contextId)` — a CALayer that renders the remote context
+6. CALayerHost added as sublayer to JUCE editor's NSView → plugin GUI appears embedded
 
-## HOW TO DEBUG
+---
 
-1. Check Ableton log:
-```bash
-grep -i "pluginbridge\|helper\|GUI\|layer\|port\|gui_ready" ~/Library/Preferences/Ableton/Live\ 12.4/Log.txt | tail -50
-```
+## BUILD
 
-2. Check if Helper process is running:
 ```bash
-ps aux | grep PluginBridgeHelper
+cd ~/pluginbridge && git pull
+cd build && cmake --build . --config Release 2>&1 | tail -30
 ```
 
-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
+## TEST AFTER BUILD
 
-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).
+1. Restart Ableton (plugin is auto-installed to `~/Library/Audio/Plug-Ins/VST3/`)
+2. Clear blocklist: `rm -f ~/Library/PluginBridge/blocklist.txt`
+3. Load PluginBridge → select Pro-Q 4 → GUI should appear inside the editor window
+4. Test Kickstart 2 → should NOT crash Ableton (Helper crashes, gets blocklisted)
 
-## 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
+## IF GUI STILL DOESN'T SHOW
 
+Check Ableton log for contextId and CALayerHost messages:
 ```bash
-cd ~/pluginbridge && git pull
-cd build && cmake --build . --config Release 2>&1 | tail -30
+grep -i "pluginbridge\|contextId\|CALayerHost\|gui_ready" ~/Library/Preferences/Ableton/Live\ 12.4/Log.txt | tail -30
 ```
 
-## AFTER FIXING
+The log should show:
+- `HelperPluginHost: GUI ready — contextId=<number> size=<W>x<H>`
+- `PluginBridgeEditor: CALayerHost connected (contextId=<number> <W>x<H>)`
 
-Push all changes to: https://huggingface.co/RAM2118/pluginbridge
-Update this SYNC.md with what you fixed and current status.
+If contextId is 0 or either line is missing → the specific step that's failing is identified.

Source/Helper/HelperPluginHost.h

@@ -87,6 +87,6 @@ private:
     juce::String layerPortName;
 
     // ObjC objects (stored as void* to avoid ObjC in header)
-    void* remoteLayerServer = nullptr;   // CARemoteLayerServer*
-    void* guiWindow = nullptr;           // NSWindow* (hidden, for layer backing)
+    void* caContext  = nullptr;   // CAContext* — cross-process layer server
+    void* guiWindow  = nullptr;   // NSWindow* — off-screen, ordered-front for compositing
 };

Source/Helper/HelperPluginHost.mm

@@ -8,6 +8,7 @@
 #if JUCE_MAC
 #import <Cocoa/Cocoa.h>
 #import <QuartzCore/QuartzCore.h>
+#include "PrivateCA.h"
 #endif
 
 HelperPluginHost::HelperPluginHost()
@@ -188,7 +189,7 @@ bool HelperPluginHost::setParams(const std::map<int, float>& values)
     return true;
 }
 
-// --- GUI via CARemoteLayerServer ---
+// --- GUI via CAContext + CALayerHost (cross-process layer sharing) ---
 
 void HelperPluginHost::showGui()
 {
@@ -203,19 +204,24 @@ void HelperPluginHost::showGui()
         editor.reset(plugin->createEditor());
         if (!editor) return;
 
-        guiWidth = editor->getWidth();
+        guiWidth  = editor->getWidth();
         guiHeight = editor->getHeight();
+        if (guiWidth <= 0 || guiHeight <= 0) { guiWidth = 800; guiHeight = 600; }
 
-        // Hidden NSWindow for layer-backed rendering
+        // Off-screen NSWindow positioned far off-screen so it's invisible to the user,
+        // but orderFront: is required so the WindowServer composites its layer content.
+        NSRect frame = NSMakeRect(-32000, -32000, guiWidth, guiHeight);
         NSWindow* window = [[NSWindow alloc]
-            initWithContentRect:NSMakeRect(0, 0, guiWidth, guiHeight)
+            initWithContentRect:frame
             styleMask:NSWindowStyleMaskBorderless
             backing:NSBackingStoreBuffered
             defer:NO];
         [window setReleasedWhenClosed:NO];
+        [window setOpaque:NO];
+        [window setBackgroundColor:[NSColor clearColor]];
         [[window contentView] setWantsLayer:YES];
 
-        // Add JUCE editor view
+        // Embed JUCE editor NSView inside the off-screen window
         editor->addToDesktop(0, (void*)[window contentView]);
         if (auto* peer = editor->getPeer())
         {
@@ -224,24 +230,26 @@ void HelperPluginHost::showGui()
             [editorView setFrame:[[window contentView] bounds]];
         }
 
-        // CARemoteLayerServer
-        CARemoteLayerServer* server = [CARemoteLayerServer sharedServer];
-        remoteLayerServer = (__bridge_retained void*)server;
+        // OrderFront so the WindowServer allocates a backing store and composites content.
+        // The window is off-screen so the user never sees it.
+        [window orderFront:nil];
+        guiWindow = (__bridge void*)window; // alloc/init already retains; no extra retain needed
 
-        // Register port
-        mach_port_t port = server.serverPort;
-        NSMachPort* machPort = [NSMachPort portWithMachPort:port];
-        NSString* portNameNS = [NSString stringWithUTF8String:layerPortName.toRawUTF8()];
-        [[NSMachBootstrapServer sharedInstance] registerPort:machPort name:portNameNS];
+        // CAContext wraps the content view's backing CALayer and exposes it to other
+        // processes via a uint32_t contextId sent over our existing IPC socket.
+        // We explicitly retain because we're not using ARC and this is a factory method.
+        uint32_t cgsConn = CGSMainConnectionID();
+        CAContext* ctx = [[CAContext contextWithCGSConnection:cgsConn options:@{}] retain];
+        ctx.layer = [window contentView].layer;
+        caContext = (__bridge void*)ctx;
 
-        guiWindow = (__bridge_retained void*)window;
+        uint32_t ctxId = ctx.contextId;
 
-        DBG("HelperPluginHost: GUI ready, port: " + layerPortName +
-            " size: " + juce::String(guiWidth) + "x" + juce::String(guiHeight));
+        DBG("HelperPluginHost: GUI ready — contextId=" + juce::String(ctxId) +
+            " size=" + juce::String(guiWidth) + "x" + juce::String(guiHeight));
 
-        // NOTIFY HOST that GUI is ready with port name and dimensions
         if (onGuiCreated)
-            onGuiCreated(layerPortName, guiWidth, guiHeight);
+            onGuiCreated(juce::String(ctxId), guiWidth, guiHeight);
     });
 #endif
 }
@@ -253,19 +261,21 @@ void HelperPluginHost::hideGui()
     {
         editor.reset();
 
-        if (guiWindow)
+        if (caContext)
         {
-            NSWindow* window = (__bridge_transfer NSWindow*)guiWindow;
-            [window close];
-            guiWindow = nullptr;
+            CAContext* ctx = (__bridge CAContext*)caContext;
+            ctx.layer = nil;
+            [ctx release];
+            caContext = nullptr;
         }
 
-        if (remoteLayerServer)
+        if (guiWindow)
         {
-            NSString* portNameNS = [NSString stringWithUTF8String:layerPortName.toRawUTF8()];
-            [[NSMachBootstrapServer sharedInstance] registerPort:nil name:portNameNS];
-            CFRelease(remoteLayerServer);
-            remoteLayerServer = nullptr;
+            NSWindow* window = (__bridge NSWindow*)guiWindow;
+            [window orderOut:nil];
+            [window close];
+            [window release];
+            guiWindow = nullptr;
         }
     });
 #endif

Source/Plugin/PluginBridgeEditor.mm

@@ -3,6 +3,7 @@
 #if JUCE_MAC
 #import <Cocoa/Cocoa.h>
 #import <QuartzCore/QuartzCore.h>
+#include "PrivateCA.h"
 #endif
 
 #include "json.hpp"
@@ -137,15 +138,12 @@ void PluginBridgeEditor::resized()
     mcpStatusLabel.setBounds(topBar);
 
 #if JUCE_MAC
-    // Resize the remote CALayer to fill the area below the top bar
+    // Resize the CALayerHost to fill the area below the top bar
     if (layerConnected && remoteLayerClient)
     {
-        CARemoteLayerClient* client = (__bridge CARemoteLayerClient*)remoteLayerClient;
-        if (client.layer)
-        {
-            auto body = getLocalBounds().withTrimmedTop(kTopBarHeight);
-            client.layer.frame = CGRectMake(0, 0, body.getWidth(), body.getHeight());
-        }
+        CALayerHost* hostLayer = (__bridge CALayerHost*)remoteLayerClient;
+        auto body = getLocalBounds().withTrimmedTop(kTopBarHeight);
+        hostLayer.frame = CGRectMake(0, 0, body.getWidth(), body.getHeight());
     }
 #endif
 }
@@ -195,51 +193,37 @@ void PluginBridgeEditor::connectRemoteLayer()
 #if JUCE_MAC
     disconnectRemoteLayer();
 
+    // portName is now the CAContext contextId sent as a decimal string by the Helper
     auto portName = processorRef.getRemoteLayerPortName();
     if (portName.isEmpty()) return;
 
-    int guiW = processorRef.getRemoteGuiWidth();
-    int guiH = processorRef.getRemoteGuiHeight();
-    if (guiW <= 0 || guiH <= 0) return;
-
-    // Look up the Mach port from the bootstrap server
-    NSString* nsPortName = [NSString stringWithUTF8String:portName.toRawUTF8()];
-    NSMachPort* machPort = (NSMachPort*)[[NSMachBootstrapServer sharedInstance]
-        portForName:nsPortName];
-
-    if (!machPort)
+    uint32_t contextId = (uint32_t)portName.getLargeIntValue();
+    if (contextId == 0)
     {
-        DBG("PluginBridgeEditor: Failed to look up Mach port: " + portName);
+        DBG("PluginBridgeEditor: Invalid contextId in portName: " + portName);
         return;
     }
 
-    mach_port_t port = [machPort machPort];
-
-    // Create remote layer client
-    CARemoteLayerClient* client = [[CARemoteLayerClient alloc] initWithServerPort:port];
-    if (!client)
-    {
-        DBG("PluginBridgeEditor: Failed to create CARemoteLayerClient");
-        return;
-    }
+    int guiW = processorRef.getRemoteGuiWidth();
+    int guiH = processorRef.getRemoteGuiHeight();
+    if (guiW <= 0 || guiH <= 0) return;
 
-    remoteLayerClient = (__bridge_retained void*)client;
+    // CALayerHost embeds the Helper's CAContext layer into our view hierarchy.
+    // No Mach port lookup needed — contextId is the only thing required.
+    // Explicitly retain — no ARC in this target, and layer is a factory method.
+    CALayerHost* hostLayer = [[CALayerHost layer] retain];
+    hostLayer.contextId = contextId;
+    hostLayer.frame = CGRectMake(0, 0, guiW, guiH);
+    remoteLayerClient = (__bridge void*)hostLayer;
 
-    // Get our NSView and make it layer-backed
+    // Make JUCE's NSView layer-backed and add the host layer as a sublayer
     if (auto* peer = getPeer())
     {
         NSView* nsView = (NSView*)peer->getNativeHandle();
         [nsView setWantsLayer:YES];
 
-        // Add remote layer as sublayer, positioned below the top bar
-        CALayer* remoteLayer = client.layer;
-        if (remoteLayer)
-        {
-            remoteLayer.frame = CGRectMake(0, 0, guiW, guiH);
-            // Position at the bottom of the view (below top bar)
-            // NSView coordinates are flipped (0,0 = bottom-left)
-            [nsView.layer addSublayer:remoteLayer];
-        }
+        if (nsView.layer)
+            [nsView.layer addSublayer:hostLayer];
     }
 
     layerConnected = true;
@@ -247,7 +231,8 @@ void PluginBridgeEditor::connectRemoteLayer()
     // Resize editor to fit plugin GUI + top bar
     setSize(std::max(guiW, kDefaultWidth), guiH + kTopBarHeight);
 
-    DBG("PluginBridgeEditor: Remote layer connected (" + juce::String(guiW) + "x" + juce::String(guiH) + ")");
+    DBG("PluginBridgeEditor: CALayerHost connected (contextId=" + juce::String(contextId) +
+        " " + juce::String(guiW) + "x" + juce::String(guiH) + ")");
 #endif
 }
 
@@ -256,9 +241,9 @@ void PluginBridgeEditor::disconnectRemoteLayer()
 #if JUCE_MAC
     if (remoteLayerClient)
     {
-        CARemoteLayerClient* client = (__bridge_transfer CARemoteLayerClient*)remoteLayerClient;
-        if (client.layer)
-            [client.layer removeFromSuperlayer];
+        CALayerHost* hostLayer = (__bridge CALayerHost*)remoteLayerClient;
+        [hostLayer removeFromSuperlayer];
+        [hostLayer release];
         remoteLayerClient = nullptr;
     }
     layerConnected = false;

Source/Shared/PrivateCA.h

@@ -0,0 +1,22 @@
+#pragma once
+// Private QuartzCore + CoreGraphics APIs for cross-process layer hosting.
+// CAContext/CALayerHost have been stable from macOS 10.10 through Sequoia (15.x).
+// No entitlements needed — works for same-user processes.
+
+#import <Foundation/Foundation.h>
+#import <QuartzCore/QuartzCore.h>
+
+// WindowServer connection ID for the current process
+extern "C" uint32_t CGSMainConnectionID(void);
+
+// CAContext — server side: wraps a CALayer and exposes it to other processes via contextId
+@interface CAContext : NSObject
++ (instancetype)contextWithCGSConnection:(uint32_t)cid options:(NSDictionary *)opts;
+@property (readonly) uint32_t contextId;
+@property (retain)   CALayer *layer;
+@end
+
+// CALayerHost — client side: a CALayer subclass that renders a remote CAContext by ID
+@interface CALayerHost : CALayer
+@property uint32_t contextId;
+@end