@nimblebrain/synapse 0.12.0 → 0.12.2

package/README.md

@@ -37,6 +37,10 @@ npm install @nimblebrain/synapse
 
 **Peer dependency:** `@modelcontextprotocol/ext-apps@^1.3.1`
 
+**Building a Python MCP server?** The server half — one self-contained `ui://`
+component rendered across ChatGPT, Claude, and NimbleBrain — ships as the
+[`nimblebrain-synapse`](python/README.md) PyPI package (`pip install nimblebrain-synapse`).
+
 ## Package Exports
 
 | Entry Point | Description |
@@ -78,8 +82,10 @@ These are the durable decisions behind the library; they rarely change.
 - **Responsive to the pane, not the device.** Layouts observe their own width
   (`ResizeObserver` via `useBreakpoint`), because an app's iframe may be
   fullscreen, split, or a narrow rail regardless of screen size.
-- **Lean on the platform.** `Drawer` is built on the native `<dialog>` element
-  (focus-trap, Escape, scroll behavior for free) rather than re-implementing them.
+- **Sandbox-safe overlays.** `Drawer` is a plain `<div>` overlay, not a native
+  `<dialog>`: the app iframe withholds `allow-modals`, so `<dialog>.showModal()`
+  throws there. The scrim, Tab focus trap, focus-in/restore, scroll-lock, and
+  Escape are hand-rolled.
 
 ## Quick Start
 
@@ -113,7 +119,7 @@ app.updateModelContext(
 ### React
 
 ```tsx
-import { AppProvider, useToolResult, useCallTool, useResize } from "@nimblebrain/synapse/react";
+import { AppProvider, useToolResult, useResize } from "@nimblebrain/synapse/react";
 
 function App() {
   return (
@@ -125,7 +131,6 @@ function App() {
 
 function ItemList() {
   const result = useToolResult();
-  const { call, data, isPending } = useCallTool("list_items");
   const resize = useResize();
 
   useEffect(() => { if (result) resize(); }, [result, resize]);
@@ -336,7 +341,7 @@ await synapse.ready;
 | `ready` | Promise that resolves after the ext-apps handshake |
 | `isNimbleBrainHost` | Whether the host is a NimbleBrain platform |
 | `callTool(name, args?)` | Call an MCP tool and get typed result |
-| `callToolAsTask(name, args?, opts?)` | Call a long-running tool task-augmented; returns a `TaskHandle` immediately. See [Long-running tools](#long-running-tools-tasks) below. |
+| `callToolAsTask(name, args?, opts?)` | Call a long-running tool task-augmented; returns a `Promise<TaskHandle>`. See [Long-running tools](#long-running-tools-tasks) below. |
 | `onDataChanged(cb)` | Subscribe to data change events |
 | `onAction(cb)` | Subscribe to agent actions (typed, declarative) |
 | `getTheme()` | Get current theme |
@@ -359,7 +364,7 @@ await synapse.ready;
 Wrap your app with `<AppProvider>` and use these hooks. Each is a thin wrapper over `connect()`.
 
 ```tsx
-import { AppProvider, useApp, useToolResult, useToolInput, useResize, useCallTool } from "@nimblebrain/synapse/react";
+import { AppProvider, useApp, useToolResult, useToolInput, useResize } from "@nimblebrain/synapse/react";
 ```
 
 | Hook | Returns | Description |
@@ -369,7 +374,8 @@ import { AppProvider, useApp, useToolResult, useToolInput, useResize, useCallToo
 | `useToolInput()` | `Record<string, unknown> \| null` | Re-renders on every `tool-input` event |
 | `useConnectTheme()` | `Theme` | Reactive theme from `connect()` |
 | `useResize()` | `(w?, h?) => void` | Resize helper — auto-measures body if no args |
-| `useCallTool(name)` | `{ call, data, isPending, error }` | Call a tool with loading/error state |
+
+To call a tool on this path, use the `App` instance: `useApp()`, then `app.callTool(name, args)`. The `useCallTool` hook (with built-in loading state) belongs to the `SynapseProvider` set below.
 
 ### `SynapseProvider`-based (Legacy)
 

package/dist/ui/index.cjs

@@ -307,21 +307,23 @@ function Card({
 }
 var STYLE_ID3 = "nb-synapse-drawer";
 var RULES3 = `
+.nb-drawer-scrim {
+  position: fixed; inset: 0; z-index: 1000;
+  display: flex; background: rgba(0, 0, 0, 0.32);
+  animation: nb-drawer-fade 200ms ease;
+}
+.nb-drawer-scrim--right { justify-content: flex-end; }
+.nb-drawer-scrim--left { justify-content: flex-start; }
+.nb-drawer-scrim--bottom { align-items: flex-end; }
 .nb-drawer {
   margin: 0; padding: 0; border: none; max-width: 92%;
   height: 100%; max-height: 100%; display: flex; flex-direction: column;
+  outline: none;
 }
-.nb-drawer--right { margin-left: auto; }
-.nb-drawer--left { margin-right: auto; }
-.nb-drawer--bottom {
-  margin-top: auto; width: 100%; max-width: 100%;
-  height: auto; max-height: 92%;
-}
-.nb-drawer--right[open] { animation: nb-drawer-in-right 240ms cubic-bezier(0.2, 0, 0, 1); }
-.nb-drawer--left[open] { animation: nb-drawer-in-left 240ms cubic-bezier(0.2, 0, 0, 1); }
-.nb-drawer--bottom[open] { animation: nb-drawer-in-bottom 240ms cubic-bezier(0.2, 0, 0, 1); }
-.nb-drawer::backdrop { background: rgba(0, 0, 0, 0.32); }
-.nb-drawer[open]::backdrop { animation: nb-drawer-fade 200ms ease; }
+.nb-drawer--bottom { width: 100%; max-width: 100%; height: auto; max-height: 92%; }
+.nb-drawer--right { animation: nb-drawer-in-right 240ms cubic-bezier(0.2, 0, 0, 1); }
+.nb-drawer--left { animation: nb-drawer-in-left 240ms cubic-bezier(0.2, 0, 0, 1); }
+.nb-drawer--bottom { animation: nb-drawer-in-bottom 240ms cubic-bezier(0.2, 0, 0, 1); }
 @keyframes nb-drawer-in-right { from { transform: translateX(100%); } }
 @keyframes nb-drawer-in-left { from { transform: translateX(-100%); } }
 @keyframes nb-drawer-in-bottom { from { transform: translateY(100%); } }
@@ -331,6 +333,18 @@ var RULES3 = `
   .nb-drawer-iconbtn { min-width: 44px; min-height: 44px; }
 }
 `;
+function inClosedDetails(el) {
+  const details = el.closest("details:not([open])");
+  if (!details) return false;
+  const summary = details.querySelector("summary");
+  return !summary || !summary.contains(el);
+}
+var CANDIDATES = "a[href], button, input, select, textarea, summary, [tabindex]";
+function tabbables(panel) {
+  return Array.from(panel.querySelectorAll(CANDIDATES)).filter(
+    (el) => el.tabIndex >= 0 && !el.matches(":disabled") && !el.closest("[hidden]") && !inClosedDetails(el) && el.type !== "hidden"
+  );
+}
 var DrawerContext = react.createContext(null);
 function DrawerRoot({
   open,
@@ -343,41 +357,86 @@ function DrawerRoot({
   ...rest
 }) {
   chunkRX6XCLFF_cjs.ensureStyle(STYLE_ID3, RULES3);
-  const dialogRef = react.useRef(null);
+  const panelRef = react.useRef(null);
   const labelId = react.useId();
   const [hasTitle, setHasTitle] = react.useState(false);
   react.useEffect(() => {
-    const dialog = dialogRef.current;
-    if (!dialog || typeof dialog.showModal !== "function") return;
-    if (open && !dialog.open) dialog.showModal();
-    else if (!open && dialog.open) dialog.close();
+    if (!open) return;
+    const onKey = (e) => {
+      if (e.key === "Escape") {
+        e.preventDefault();
+        (onEscape ?? onClose)();
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [open, onEscape, onClose]);
+  react.useEffect(() => {
+    if (!open) return;
+    const panel = panelRef.current;
+    const previouslyFocused = document.activeElement;
+    panel?.focus();
+    const { body } = document;
+    const prevOverflow = body.style.overflow;
+    body.style.overflow = "hidden";
+    const onKeyDown = (e) => {
+      if (e.key !== "Tab" || !panel) return;
+      const focusables = tabbables(panel);
+      if (focusables.length === 0) {
+        e.preventDefault();
+        return;
+      }
+      const first = focusables[0];
+      const last = focusables[focusables.length - 1];
+      const active = document.activeElement;
+      if (e.shiftKey && (active === first || active === panel)) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && active === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    };
+    panel?.addEventListener("keydown", onKeyDown);
+    return () => {
+      panel?.removeEventListener("keydown", onKeyDown);
+      body.style.overflow = prevOverflow;
+      previouslyFocused?.focus?.();
+    };
   }, [open]);
+  const ctxValue = react.useMemo(() => ({ labelId, setHasTitle }), [labelId]);
+  if (!open) return null;
   const isBottom = side === "bottom";
   const panelStyle = {
     ...isBottom ? { width: "100%", maxWidth: "100%" } : { width },
     background: tokens.bg,
     color: tokens.fg,
     boxShadow: tokens.shadowLg,
+    outline: "none",
     ...side === "right" ? { borderLeft: `${tokens.borderWidth} solid ${tokens.border}` } : side === "left" ? { borderRight: `${tokens.borderWidth} solid ${tokens.border}` } : { borderTop: `${tokens.borderWidth} solid ${tokens.border}` },
     ...style
   };
-  const ctxValue = react.useMemo(() => ({ labelId, setHasTitle }), [labelId]);
   return /* @__PURE__ */ jsxRuntime.jsx(DrawerContext.Provider, { value: ctxValue, children: /* @__PURE__ */ jsxRuntime.jsx(
-    "dialog",
+    "div",
     {
-      ref: dialogRef,
-      className: `nb-drawer nb-drawer--${side}`,
-      style: panelStyle,
-      "aria-labelledby": hasTitle ? labelId : void 0,
-      onCancel: (e) => {
-        e.preventDefault();
-        (onEscape ?? onClose)();
-      },
+      className: `nb-drawer-scrim nb-drawer-scrim--${side}`,
       onClick: (e) => {
-        if (e.target === dialogRef.current) onClose();
+        if (e.target === e.currentTarget) onClose();
       },
-      ...rest,
-      children
+      children: /* @__PURE__ */ jsxRuntime.jsx(
+        "div",
+        {
+          ref: panelRef,
+          role: "dialog",
+          "aria-modal": "true",
+          "aria-labelledby": hasTitle ? labelId : void 0,
+          tabIndex: -1,
+          className: `nb-drawer nb-drawer--${side}`,
+          style: panelStyle,
+          ...rest,
+          children
+        }
+      )
     }
   ) });
 }