fix(ide): composite overlays above Scintilla (#46)

* fix(ide): composite overlays above Scintilla

* fix(ide): share platform overlay surface

Author: icecreamx10

.changeset/ide-overlay-and-workspace.md

@@ -0,0 +1,32 @@
+---
+'lynxtron-go': patch
+---
+
+Three fixes found while testing the IDE surface.
+
+**The palette opened behind the code.** Native Scintilla views paint above all
+Lynx UI whatever the z-index says, so an overlay does not cover the editor — the
+editor covers the overlay. The palette, gallery, dialogs, loading state, and
+toasts now register with one shared `cover-view` host, which composites their
+children into a platform overlay slice above native views without creating a
+second macOS overlay surface during rapid modal transitions. The Scintilla extension now keeps the
+originating `lynx_view_t`, mounts its NSView/HWND under that view's native
+parent, and keeps the editor below Clay's overlay host instead of guessing the
+key window and floating above the entire Lynx surface. Editors stay attached
+while overlays are open, preserving focus, selection, scroll position, and
+paint state.
+
+**One resolver, and reuse what is already on disk.** The Fiddle and the IDE are
+two views of one workspace, but each carried its own copy of "local source tree,
+else fetch" — two functions meaning the same thing, free to drift, sharing every
+failure anyway. They now share one, which also gained the step both were
+missing: `fetch` wipes and re-extracts its destination on every call, so opening
+a showcase in the Fiddle and then in the IDE downloaded and installed the same
+workspace twice, seconds apart. A materialized workspace is now reused, verified
+by reading its manifest so a half-extracted directory from an interrupted fetch
+is not mistaken for a usable one.
+
+**A failed workspace says so.** A window opened to prepare a showcase that never
+arrived showed the same "Open Folder" invitation as an idle one; the reason sat
+in the Output panel, which is closed by default. The editor area now names the
+failure and offers Try again.

AGENTS.md

@@ -75,7 +75,10 @@ succeeds, use the supported behaviour and update this list.
 - Probe the *actual* object exposed to the UI. A bridge intended as `foundation.*` was in fact spread onto the exposed root, and optional chaining hid every dead call.
 
 **Native views**
-- Native child views float above all Lynx UI and are not clipped by Lynx ancestors. Give hosts `min-width: 0`, `min-height: 0`, `overflow: hidden` and verify in the real window.
+- Native child views float above the regular Lynx surface and are not clipped by Lynx ancestors. Give hosts `min-width: 0`, `min-height: 0`, `overflow: hidden` and verify in the real window.
+- UI that must cover a native child view must use a `<cover-view>` root. Clay renders its children into a platform overlay slice; ordinary `<view>` plus `z-index` cannot cross the native-view boundary. Keep the covered native view attached so focus, selection, scroll position, and paint state remain stable.
+- Route application overlays through one shared `<cover-view>` host on the current macOS runtime. Rapidly adding a second external overlay surface can race Clay's asynchronous present path; a single host can stack multiple Lynx overlay subtrees without exercising that surface-growth path.
+- A desktop native view must use the `lynx_view_t` passed as its registration opaque to resolve `lynx_view_get_native_window()`. On macOS mount it inside the returned renderer view so Clay's sibling `ClayOverlayView` remains above the whole subtree. On Windows use a child HWND under the returned parent and do not raise it above Clay's child overlay windows. Never rediscover the host via `keyWindow`, foreground-window enumeration, or an owned popup — those escape Clay's overlay ordering and break multi-window isolation.
 - Content pushed before the first attach lands in the document but does not repaint. Re-sync after the first layout.
 - Devtool screenshots **cannot see native views** — capture the OS window instead (`screencapture -x -l <CGWindowID>`).
 

lynxtron-go/scintilla-extension/module/scintilla_extension_module.cc

@@ -506,7 +506,7 @@ Napi::Value ScintillaExtensionModuleMethodsBinder(
 
 void ScintillaExtensionModule::OnLynxViewCreate(lynx_view_t* lynx_view) {
   lynx_view_register_native_view(lynx_view, "scintilla-view",
-                                 &scintilla_view_create_view, nullptr);
+                                 &scintilla_view_create_view, lynx_view);
 }
 void ScintillaExtensionModule::OnLynxViewDestroy() {}
 void ScintillaExtensionModule::OnRuntimeInit() {}

lynxtron-go/scintilla-extension/module/scintilla_view.h

@@ -18,7 +18,7 @@ namespace extension {
 
 class ScintillaView : public lynx::pub::LynxNativeView {
  public:
-  ScintillaView();
+  explicit ScintillaView(lynx_view_t* lynx_view);
   ~ScintillaView();
 
   bool IsSurfaceEnabled() override { return false; } // Use a platform child view directly, not a surface.
@@ -90,6 +90,10 @@ class ScintillaView : public lynx::pub::LynxNativeView {
   void ApplyTheme(bool dark, int size_pt);
 
 private:
+  // Non-owning. The LynxView owns every registered native-view instance and
+  // outlives it. Keeping the originating view removes the key-window/global
+  // HWND heuristics and gives each editor the correct platform parent.
+  lynx_view_t* lynx_view_ = nullptr;
   void* cocoa_view_ = nullptr; // Pointer to ScintillaCocoa (NSView)
   void* win_host_ = nullptr;   // Pointer to the Win32 child host HWND
   void* win_view_ = nullptr;   // Pointer to the Win32 Scintilla HWND
@@ -103,8 +107,8 @@ class ScintillaView : public lynx::pub::LynxNativeView {
   bool has_pending_content_ = false;
   std::string editor_id_;
   std::atomic<bool> content_changed_{false};
-  // Host-driven detach (dialogs/overlays/drags): while set, OnLayoutChanged's
-  // lazy attach must NOT re-add the view — it would float above the overlay.
+  // Explicit route/host detach: while set, OnLayoutChanged must not re-add
+  // the view until AttachToWindow clears it.
   std::atomic<bool> detached_by_host_{false};
   // Last layout rect (pt) so AttachToWindow can restore the frame even when
   // layout changed while detached. Guarded by dwell_mutex_ (written on the

lynxtron-go/scintilla-extension/module/scintilla_view.mm

@@ -140,6 +140,29 @@ - (void)notification:(SCNotification*)n {
 
 namespace extension {
 
+#ifdef __APPLE__
+namespace {
+
+void MountInLynxRendererHost(NSView* parent, NSView* nativeView) {
+    if (!parent || !nativeView) return;
+    if (nativeView.superview != parent) {
+        [nativeView removeFromSuperview];
+        [parent addSubview:nativeView];
+    }
+}
+
+NSRect FrameInPlatformParent(NSView* parent, float left, float top,
+                             float width, float height) {
+    if (parent.isFlipped) {
+        return NSMakeRect(left, top, width, height);
+    }
+    return NSMakeRect(left, parent.bounds.size.height - top - height,
+                      width, height);
+}
+
+}  // namespace
+#endif
+
 // Diagnostic logging is opt-in: OnLayoutChanged fires on every sash-drag
 // frame, so unconditional printf turns a drag into a stdout flood. Set
 // LYNXTRON_SCINTILLA_LOG=1 to trace the attach/layout lifecycle (the
@@ -150,7 +173,8 @@ static bool ScxVerbose() {
 }
 #define SCX_LOG(...) do { if (ScxVerbose()) { printf(__VA_ARGS__); fflush(stdout); } } while (0)
 
-ScintillaView::ScintillaView() {
+ScintillaView::ScintillaView(lynx_view_t* lynx_view)
+    : lynx_view_(lynx_view) {
     SCX_LOG("ScintillaView::ScintillaView constructor called\n");
 #ifdef __APPLE__
     // Ensure UI operations happen on main thread
@@ -281,9 +305,9 @@ static bool ScxVerbose() {
         }
     }
 
-    // Host suppression state (dialog/overlay open) must land before the
-    // first layout pass — panes created UNDER an open dialog (mosaic rebuild
-    // while Settings is up) would otherwise lazily attach above it.
+    // Backward-compatible explicit host-detach state. Product overlays now
+    // use cover-view and leave Scintilla mounted below ClayOverlayView; route
+    // or workspace transitions may still use this channel.
     if (attrs.HasProperty("suppressed")) {
         std::string v = attrs.GetProperty("suppressed").StdString();
         bool sup = !(v == "false" || v == "0");
@@ -342,21 +366,17 @@ static bool ScxVerbose() {
     if (detached_by_host_.load(std::memory_order_relaxed)) return;
     ScintillaViewContainer* container = (__bridge ScintillaViewContainer*)cocoa_view_;
     // So we just need to ensure the container resizes its subviews (ScintillaView).
-    auto attachToWindow = [container]() {
+    lynx_view_t* lynx_view = lynx_view_;
+    auto attachToWindow = [container, lynx_view]() {
         if (container.hostDetached) return; // detach won the race — stay out
-        if (container.superview != nil) return;
-        // Prefer keyWindow, fall back to mainWindow, then first available
-        // window. KNOWN LIMITATION: with several windows in one process this
-        // can attach to whichever window happens to be key — the fallback
-        // chain is a heuristic, not multi-window support (gap 2b).
-        NSWindow* window = [NSApp keyWindow];
-        if (!window) window = [NSApp mainWindow];
-        if (!window) window = [[NSApp windows] firstObject];
-        if (window) {
-            SCX_LOG("ScintillaView::OnLayoutChanged: Adding container to window contentView\n");
-            [window.contentView addSubview:container];
+        NSView* parent = lynx_view
+            ? (__bridge NSView*)lynx_view_get_native_window(lynx_view)
+            : nil;
+        if (parent) {
+            SCX_LOG("ScintillaView::OnLayoutChanged: Mounting in Lynx renderer host\n");
+            MountInLynxRendererHost(parent, container);
         } else {
-            SCX_LOG("ScintillaView::OnLayoutChanged: Warning - No window found to add subview\n");
+            SCX_LOG("ScintillaView::OnLayoutChanged: Warning - Lynx native parent unavailable\n");
         }
     };
 
@@ -366,10 +386,7 @@ static bool ScxVerbose() {
     auto setFrameInWindow = [container, left, top, width, height]() {
         NSView* parent = container.superview;
         if (!parent) return;
-        CGFloat parentH = parent.bounds.size.height;
-        CGFloat flippedY = parentH - top - height;
-        NSRect frame = NSMakeRect(left, flippedY, width, height);
-        [container setFrame:frame];
+        [container setFrame:FrameInPlatformParent(parent, left, top, width, height)];
     };
 
     if ([NSThread isMainThread]) {
@@ -618,25 +635,19 @@ static bool ScxVerbose() {
     }
     auto doAttach = ^{
         container.hostDetached = NO;
-        if (container.superview == nil) {
-            NSWindow* window = [NSApp keyWindow];
-            if (!window) window = [NSApp mainWindow];
-            if (!window) window = [[NSApp windows] firstObject];
-            if (window) {
-                [window.contentView addSubview:container];
-            } else {
-                SCX_LOG("ScintillaView::AttachToWindow: Warning - No window found to add subview\n");
-                return;
-            }
+        NSView* parent = lynx_view_
+            ? (__bridge NSView*)lynx_view_get_native_window(lynx_view_)
+            : nil;
+        if (!parent) {
+            SCX_LOG("ScintillaView::AttachToWindow: Warning - Lynx native parent unavailable\n");
+            return;
         }
+        MountInLynxRendererHost(parent, container);
         // Restore the LAST layout rect — the layout may have changed while we
         // were detached (sash drags relayout constantly) and those
         // OnLayoutChanged passes intentionally skipped attach/setFrame.
         if (w > 0 && h > 0 && container.superview != nil) {
-            NSView* parent = container.superview;
-            CGFloat parentH = parent.bounds.size.height;
-            CGFloat flippedY = parentH - top - h;
-            [container setFrame:NSMakeRect(left, flippedY, w, h)];
+            [container setFrame:FrameInPlatformParent(parent, left, top, w, h)];
         }
     };
     if ([NSThread isMainThread]) {
@@ -805,7 +816,8 @@ static bool ScxVerbose() {
 }  // namespace extension
 
 LYNX_EXTERN_C lynx_native_view_t* scintilla_view_create_view(void* opaque) {
-  auto* view = new extension::ScintillaView();
+  auto* view = new extension::ScintillaView(
+      static_cast<lynx_view_t*>(opaque));
 
   auto* native_wrapper = view->native_view();