feat(notebook): drive the map from external Jupyter clients (VS Code) (#1444)

* feat(notebook): drive the map from external Jupyter clients

`geolibre.connect()` sent every map command as a `display(Javascript(...))`
that posts to `window.parent`, so it only reached the map when the notebook
was rendered inside the app's own Notebook-panel iframe. Attaching an
external frontend to the desktop app's Jupyter server (VS Code's Jupyter
extension, `jupyter console`, nbclient) ran cells fine but made every
`fly_to`/`add_geojson` silently do nothing.

Add a transport that depends on which SERVER the kernel belongs to rather
than on how the notebook is displayed:

- `geolibre_server/jupyter_relay.py`, a Jupyter Server extension enabled from
  `jupyter_server_config.py`, exposing `POST .../geolibre/relay/command`, a
  `.../geolibre/relay/socket` WebSocket and `GET .../geolibre/relay/status`.
  At load it publishes `GEOLIBRE_RELAY_URL`/`GEOLIBRE_RELAY_TOKEN` into the
  server environment, which kernels inherit, so `import geolibre` finds the
  map with no configuration and no launcher change.
- `useJupyterRelay` subscribes the app to that socket for its whole lifetime
  (reconnecting with backoff) and runs commands against the same
  `createScriptingHandlers` surface as `useNotebookBridge` and the console.
- The kernel client prefers the relay and keeps postMessage as the fallback
  for the embedded panel and JupyterLite. The POST reports how many windows
  received the command, so an undeliverable call now raises a
  `GeoLibreNotConnectedWarning` pointing at the user's own line instead of
  quietly succeeding; `geolibre.is_connected()` exposes the same state.
- The Notebook panel gains a button that copies the server URL an external
  client attaches to, since that is the only setup step left.

Every endpoint requires the server's per-launch token and the socket accepts
only the app's own origins, so a command can only come from something that
already has kernel-execution rights on this loopback server.

Fixes #1442

* fix(notebook): handle a rejected clipboard copy and modernize the abc imports

Addresses CodeRabbit review on #1444: navigator.clipboard.writeText can
reject, which left an unhandled rejection and could show the copied
confirmation for a copy that never happened; and Iterable/Sequence now come
from collections.abc (UP035).

Author: giswqs

apps/geolibre-desktop/src/components/layout/DesktopShell.tsx

@@ -114,6 +114,7 @@ import { KnowledgeCardConsentDialog } from "./KnowledgeCardConsentDialog";
 import { MapGrid } from "./MapGrid";
 import { RemoteCursorsOverlay } from "./RemoteCursorsOverlay";
 import { useCommandBridge } from "../../hooks/useCommandBridge";
+import { useJupyterRelay } from "../../hooks/useJupyterRelay";
 import { appendDiagnostic, useDiagnosticsSnapshot } from "../../lib/diagnostics";
 import { SectionErrorBoundary, SilentErrorBoundary } from "../common/error-boundaries";
 import { AttributeTable } from "../panels/AttributeTable";
@@ -747,6 +748,10 @@ export function DesktopShell({
   // Request/reply + event channel backing the Python scripting API (live
   // queries, processing, map events). Also inert when not embedded.
   useCommandBridge(mapControllerRef);
+  // Same scripting surface, reached over the desktop Jupyter server's relay, so
+  // a kernel driven from an EXTERNAL client (VS Code's Jupyter extension) can
+  // control the map too. Inert until that server is running.
+  useJupyterRelay(mapControllerRef);
   // Routes the Layers-panel Identify action to the raster pixel inspector for
   // COG layers (read band values on click). Inert until a COG is identified.
   useRasterIdentify();

apps/geolibre-desktop/src/components/panels/NotebookPanel.tsx

@@ -1,6 +1,14 @@
 import { useAppStore } from "@geolibre/core";
 import { Button } from "@geolibre/ui";
-import { Loader2, NotebookPen, PanelRightClose, PanelRightOpen, X } from "lucide-react";
+import {
+  Check,
+  Link2,
+  Loader2,
+  NotebookPen,
+  PanelRightClose,
+  PanelRightOpen,
+  X,
+} from "lucide-react";
 import {
   type PointerEvent as ReactPointerEvent,
   type RefObject,
@@ -15,7 +23,7 @@ import { useNotebookBridge } from "../../hooks/useNotebookBridge";
 import { useNotebookThemeSync } from "../../hooks/useNotebookThemeSync";
 import type { ThemeMode } from "../../hooks/useThemeMode";
 import { isTauri } from "../../lib/is-tauri";
-import { startJupyterServer } from "../../lib/jupyter";
+import { type JupyterServerInfo, startJupyterServer } from "../../lib/jupyter";
 
 /**
  * Resolve the notebook iframe URL for the current environment:
@@ -24,13 +32,24 @@ import { startJupyterServer } from "../../lib/jupyter";
  *   embed its token-authenticated `/lab` URL.
  * - **Web:** load the self-hosted JupyterLite site (in-browser Pyodide kernel)
  *   built by `npm run build:jupyterlite` into `public/jupyterlite/`.
+ *
+ * @returns The iframe `src`, plus the desktop server it belongs to (null on web,
+ *   where there is no server an external client could attach to).
  */
-async function resolveNotebookUrl(): Promise<string> {
+async function resolveNotebook(): Promise<{ src: string; server: JupyterServerInfo | null }> {
   if (isTauri()) {
     const info = await startJupyterServer();
-    return `${info.url}/lab?token=${encodeURIComponent(info.token)}`;
+    return {
+      src: `${info.url}/lab?token=${encodeURIComponent(info.token)}`,
+      server: info,
+    };
   }
-  return `${import.meta.env.BASE_URL}jupyterlite/lab/index.html`;
+  return { src: `${import.meta.env.BASE_URL}jupyterlite/lab/index.html`, server: null };
+}
+
+/** The URL an external Jupyter client (VS Code…) attaches to this server with. */
+function externalClientUrl(server: JupyterServerInfo): string {
+  return `${server.url}/?token=${encodeURIComponent(server.token)}`;
 }
 
 interface NotebookPanelProps {
@@ -62,6 +81,8 @@ export function NotebookPanel({ onResizeStart, mapControllerRef, themeMode }: No
   const [isCollapsed, setIsCollapsed] = useState(getIsMobileViewport);
   const [loaded, setLoaded] = useState(false);
   const [src, setSrc] = useState<string | null>(null);
+  const [server, setServer] = useState<JupyterServerInfo | null>(null);
+  const [copied, setCopied] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const iframeRef = useRef<HTMLIFrameElement>(null);
 
@@ -74,9 +95,11 @@ export function NotebookPanel({ onResizeStart, mapControllerRef, themeMode }: No
   // which can take a moment on first run while uv syncs the environment).
   useEffect(() => {
     let cancelled = false;
-    resolveNotebookUrl()
-      .then((url) => {
-        if (!cancelled) setSrc(url);
+    resolveNotebook()
+      .then(({ src: url, server: info }) => {
+        if (cancelled) return;
+        setSrc(url);
+        setServer(info);
       })
       .catch((err: unknown) => {
         if (cancelled) return;
@@ -96,6 +119,13 @@ export function NotebookPanel({ onResizeStart, mapControllerRef, themeMode }: No
     };
   }, [t]);
 
+  // Revert the copy button's confirmation so it reads as reusable.
+  useEffect(() => {
+    if (!copied) return;
+    const timer = setTimeout(() => setCopied(false), 2000);
+    return () => clearTimeout(timer);
+  }, [copied]);
+
   return (
     <aside
       aria-label={t("notebook.title")}
@@ -137,6 +167,36 @@ export function NotebookPanel({ onResizeStart, mapControllerRef, themeMode }: No
             <NotebookPen className="h-4 w-4 text-muted-foreground" />
             <span className="text-sm font-semibold">{t("notebook.title")}</span>
             <div className="ms-auto flex items-center gap-1">
+              {/* Desktop only: the loopback server URL + token an external
+                  Jupyter client (VS Code's Jupyter extension, `jupyter
+                  console`) attaches to. Such a client drives the map through the
+                  relay (useJupyterRelay), not through this iframe. */}
+              {server ? (
+                <Button
+                  variant="ghost"
+                  size="icon"
+                  className="h-7 w-7"
+                  title={copied ? t("notebook.serverUrlCopied") : t("notebook.copyServerUrl")}
+                  aria-label={t("notebook.copyServerUrl")}
+                  onClick={() => {
+                    void navigator.clipboard
+                      ?.writeText(externalClientUrl(server))
+                      .then(() => setCopied(true))
+                      .catch((error: unknown) => {
+                        // Clipboard access can be denied; never leave the button
+                        // claiming a copy that did not happen.
+                        setCopied(false);
+                        console.error("Could not copy the Jupyter server URL", error);
+                      });
+                  }}
+                >
+                  {copied ? (
+                    <Check className="h-4 w-4 text-primary" />
+                  ) : (
+                    <Link2 className="h-4 w-4" />
+                  )}
+                </Button>
+              ) : null}
               <Button
                 variant="ghost"
                 size="icon"

apps/geolibre-desktop/src/hooks/useJupyterRelay.ts

@@ -0,0 +1,120 @@
+import { type RefObject, useEffect } from "react";
+import type { MapController } from "@geolibre/map";
+import { subscribeJupyterServer } from "../lib/jupyter";
+import {
+  type RelayCommand,
+  parseRelayMessage,
+  relayReconnectDelay,
+  relaySocketUrl,
+} from "../lib/jupyter-relay";
+import { createScriptingHandlers } from "../lib/scripting/scriptingApi";
+
+// The app side of the desktop Jupyter map-command relay. This is the SIBLING of
+// useNotebookBridge: that one receives commands over postMessage from the
+// notebook iframe the app embeds, which only works while the notebook is
+// rendered inside the Notebook panel. This one subscribes to a loopback
+// WebSocket on the Jupyter server itself, so a kernel driven by ANY frontend —
+// notably VS Code's Jupyter extension attached to the same server — reaches the
+// same map (issue #1442).
+//
+// Both feed the SAME createScriptingHandlers surface used by the in-app Python
+// console and the Jupyter widget, so behaviour cannot drift between transports.
+
+/**
+ * Subscribe to the desktop Jupyter server's map-command relay for the app's
+ * lifetime, running each relayed command against the live map.
+ *
+ * Connects whenever a Jupyter server is running (started by the Notebook panel)
+ * and reconnects with backoff if the socket drops. Inert on web and on desktop
+ * until a server has been started.
+ *
+ * @param mapControllerRef - Ref to the live map controller, read lazily by the
+ *   command handlers.
+ */
+export function useJupyterRelay(mapControllerRef: RefObject<MapController | null>): void {
+  useEffect(() => {
+    const handlers = createScriptingHandlers({
+      getController: () => mapControllerRef.current,
+    });
+
+    let socket: WebSocket | null = null;
+    let retryTimer: ReturnType<typeof setTimeout> | null = null;
+    let attempt = 0;
+    // Bumped on every server change/unmount so a socket opened for a previous
+    // server can never resurrect the reconnect loop after we moved on.
+    let generation = 0;
+
+    const run = async (command: RelayCommand) => {
+      // Own-property only, so an inherited member ("constructor", …) can never be
+      // invoked as a command.
+      if (!Object.hasOwn(handlers, command.method)) {
+        console.warn(`Jupyter relay: unknown command "${command.method}"`);
+        return;
+      }
+      try {
+        await handlers[command.method](command.params);
+      } catch (error) {
+        console.error(`Jupyter relay: command "${command.method}" failed`, error);
+      }
+    };
+
+    const close = () => {
+      generation += 1;
+      if (retryTimer !== null) {
+        clearTimeout(retryTimer);
+        retryTimer = null;
+      }
+      // Drop the handlers first: onclose must not schedule a reconnect for a
+      // socket we are deliberately tearing down.
+      if (socket) {
+        socket.onclose = null;
+        socket.onerror = null;
+        socket.onmessage = null;
+        socket.close();
+        socket = null;
+      }
+    };
+
+    const unsubscribe = subscribeJupyterServer((info) => {
+      close();
+      if (!info) return;
+      const mine = generation;
+      attempt = 0;
+
+      const connect = () => {
+        if (generation !== mine) return;
+        let next: WebSocket;
+        try {
+          next = new WebSocket(relaySocketUrl(info));
+        } catch (error) {
+          console.warn("Jupyter relay: could not open the command socket", error);
+          return;
+        }
+        socket = next;
+        next.onopen = () => {
+          attempt = 0;
+        };
+        next.onmessage = (event: MessageEvent) => {
+          const command = parseRelayMessage(event.data);
+          if (command) void run(command);
+        };
+        next.onclose = () => {
+          if (generation !== mine) return;
+          socket = null;
+          // The server outlives a dropped socket (it runs for the app's
+          // lifetime), so keep retrying rather than giving up on the channel.
+          retryTimer = setTimeout(connect, relayReconnectDelay(attempt));
+          attempt += 1;
+        };
+      };
+
+      connect();
+    });
+
+    return () => {
+      unsubscribe();
+      close();
+    };
+    // Mount-only: the ref is stable and read lazily inside the handlers.
+  }, [mapControllerRef]);
+}

apps/geolibre-desktop/src/i18n/locales/en.json

@@ -2882,6 +2882,8 @@
     "collapse": "Collapse notebook",
     "expand": "Expand notebook",
     "close": "Close notebook",
+    "copyServerUrl": "Copy the server URL for external clients (VS Code…)",
+    "serverUrlCopied": "Server URL copied",
     "loading": "Loading notebook…",
     "loadFailed": "Failed to load the notebook."
   },

apps/geolibre-desktop/src/lib/jupyter-relay.ts

@@ -0,0 +1,77 @@
+import type { JupyterServerInfo } from "./jupyter";
+
+// Wire format for the desktop Jupyter map-command relay
+// (backend/geolibre_server/geolibre_server/jupyter_relay.py). The relay lets a
+// kernel drive the map regardless of which *frontend* is running the cell — the
+// embedded Notebook panel, or an external client such as VS Code's Jupyter
+// extension (issue #1442) — where the postMessage transport in useNotebookBridge
+// only reaches the map from inside the app's own iframe.
+//
+// Pure helpers live here (not in the hook) so the protocol is unit-testable.
+
+/** One scripting command relayed from a kernel, in the shared bridge envelope. */
+export interface RelayCommand {
+  method: string;
+  params: Record<string, unknown>;
+}
+
+/** URL path the relay's endpoints are mounted under, mirroring `RELAY_PATH`. */
+const RELAY_PATH = "geolibre/relay";
+
+/**
+ * Build the app-side WebSocket URL for a running Jupyter server.
+ *
+ * The token rides in the query string because a WebSocket handshake cannot carry
+ * an `Authorization` header, and the server's session cookie is unavailable to
+ * us (the app is a different origin than the loopback server).
+ *
+ * @param info - The running server's connection details.
+ * @returns A `ws://` URL for the relay socket.
+ */
+export function relaySocketUrl(info: JupyterServerInfo): string {
+  const url = new URL(`${info.url.replace(/\/+$/, "")}/${RELAY_PATH}/socket`);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  if (info.token) url.searchParams.set("token", info.token);
+  return url.toString();
+}
+
+/**
+ * Parse one relay frame into a command, rejecting anything malformed.
+ *
+ * @param data - The raw WebSocket payload.
+ * @returns The command, or null for a non-command frame (e.g. the relay's
+ *   `geolibre:relay-ready` greeting) or an unparseable one.
+ */
+export function parseRelayMessage(data: unknown): RelayCommand | null {
+  if (typeof data !== "string") return null;
+  let payload: unknown;
+  try {
+    payload = JSON.parse(data);
+  } catch {
+    return null;
+  }
+  if (!payload || typeof payload !== "object") return null;
+  const message = payload as { type?: unknown; method?: unknown; params?: unknown };
+  if (message.type !== "geolibre:command") return null;
+  if (typeof message.method !== "string" || !message.method) return null;
+  const params =
+    message.params && typeof message.params === "object" && !Array.isArray(message.params)
+      ? (message.params as Record<string, unknown>)
+      : {};
+  return { method: message.method, params };
+}
+
+/** Reconnect backoff (ms) after a dropped socket, capped so it stays responsive. */
+export const RELAY_RECONNECT_MIN_MS = 1_000;
+export const RELAY_RECONNECT_MAX_MS = 15_000;
+
+/**
+ * Next reconnect delay for a given consecutive-failure count (exponential).
+ *
+ * @param attempt - How many reconnects have already failed (0 for the first).
+ * @returns The delay in milliseconds, capped at {@link RELAY_RECONNECT_MAX_MS}.
+ */
+export function relayReconnectDelay(attempt: number): number {
+  const delay = RELAY_RECONNECT_MIN_MS * 2 ** Math.max(0, attempt);
+  return Math.min(delay, RELAY_RECONNECT_MAX_MS);
+}