@marimo-team/islands 0.23.15-dev27 → 0.23.15-dev30

package/src/core/codemirror/completion/__tests__/signature-hint.test.ts

@@ -5,6 +5,7 @@ import { EditorView, type Tooltip } from "@codemirror/view";
 import { describe, expect, it } from "vitest";
 import {
   asSignatureHint,
+  closeSignatureHint,
   setSignatureHintEffect,
   signatureHintField,
 } from "../signature-hint";
@@ -51,12 +52,79 @@ describe("signatureHintField", () => {
     expect(state.field(signatureHintField)).toBeNull();
   });
 
-  it("keeps and re-anchors the tooltip across edits", () => {
+  it("keeps and re-anchors the tooltip across edits inside the call", () => {
     let state = stateWithHint("plt.plot(", 9);
-    // Insert before the tooltip position; it should shift to stay anchored.
-    state = state.update({ changes: { from: 0, insert: "xy" } }).state;
+    // Insert before the tooltip position while the cursor stays inside the
+    // call; the anchor should shift but the hint should remain.
+    state = state.update({
+      changes: { from: 0, insert: "xy" },
+      selection: { anchor: 11 },
+    }).state;
     expect(state.field(signatureHintField)?.pos).toBe(11);
   });
+
+  it("dismisses the tooltip when the closing paren is typed", () => {
+    let state = stateWithHint("plt.plot(", 9);
+    // Type the closing paren; the cursor is now outside the call.
+    state = state.update({
+      changes: { from: 9, insert: ")" },
+      selection: { anchor: 10 },
+    }).state;
+    expect(state.field(signatureHintField)).toBeNull();
+  });
+
+  it("dismisses the tooltip when the anchored call closes inside grouping parens", () => {
+    // Regression for the `(plt.plot())` case: the outer grouping paren must not
+    // keep the (now-closed) plt.plot hint alive.
+    let state = stateWithHint("(plt.plot(", 10);
+    // Close plt.plot's call; the outer `(` is still open but we've left the
+    // anchored call.
+    state = state.update({
+      changes: { from: 10, insert: ")" },
+      selection: { anchor: 11 },
+    }).state;
+    expect(state.field(signatureHintField)).toBeNull();
+  });
+
+  it("keeps the tooltip while typing a nested call inside the anchored call", () => {
+    // Cursor inside the anchored call of `f(g(<cursor>`; opening/typing a nested
+    // call stays inside the anchored call, so the hint should remain.
+    let state = stateWithHint("f(g(", 4);
+    state = state.update({
+      changes: { from: 4, insert: "x(" },
+      selection: { anchor: 6 },
+    }).state;
+    expect(state.field(signatureHintField)?.pos).toBe(4);
+  });
+
+  it("keeps the tooltip when a nested call closes inside the anchored call", () => {
+    const anchor = "f(".length;
+    let state = stateWithHint("f(g(x", anchor);
+    state = state.update({
+      changes: { from: 5, insert: ")" },
+      selection: { anchor: 6 },
+    }).state;
+    expect(state.field(signatureHintField)?.pos).toBe(anchor);
+  });
+
+  it("dismisses the tooltip when the closing paren is typed in a large multi-line call", () => {
+    const anchor = "f(".length;
+    const prefix = `f(\n${"  x,\n".repeat(25)}`;
+    let state = EditorState.create({
+      doc: prefix,
+      selection: { anchor: prefix.length },
+      extensions: [signatureHintField],
+    });
+    state = state.update({
+      effects: setSignatureHintEffect.of(fakeTooltip(anchor)),
+    }).state;
+    const head = prefix.length;
+    state = state.update({
+      changes: { from: head, insert: ")" },
+      selection: { anchor: head + 1 },
+    }).state;
+    expect(state.field(signatureHintField)).toBeNull();
+  });
 });
 
 describe("asSignatureHint", () => {
@@ -92,3 +160,29 @@ describe("asSignatureHint", () => {
     expect(wrapped.above).toBe(true);
   });
 });
+
+describe("closeSignatureHint", () => {
+  it("returns false when no hint is showing", () => {
+    const view = new EditorView({
+      state: EditorState.create({ extensions: [signatureHintField] }),
+    });
+    expect(closeSignatureHint(view)).toBe(false);
+    expect(view.state.field(signatureHintField)).toBeNull();
+    view.destroy();
+  });
+
+  it("dismisses the hint and returns true when one is showing", () => {
+    const view = new EditorView({
+      state: EditorState.create({
+        doc: "plt.plot(",
+        extensions: [signatureHintField],
+      }),
+    });
+    view.dispatch({ effects: setSignatureHintEffect.of(fakeTooltip(9)) });
+    expect(view.state.field(signatureHintField)?.pos).toBe(9);
+
+    expect(closeSignatureHint(view)).toBe(true);
+    expect(view.state.field(signatureHintField)).toBeNull();
+    view.destroy();
+  });
+});

package/src/core/codemirror/completion/signature-hint.ts

@@ -1,12 +1,61 @@
 /* Copyright 2026 Marimo. All rights reserved. */
+import type { EditorState } from "@codemirror/state";
 import { StateEffect, StateField } from "@codemirror/state";
-import { showTooltip, type Tooltip } from "@codemirror/view";
+import { type EditorView, showTooltip, type Tooltip } from "@codemirror/view";
 
 /**
  * Effect to set (or clear, with `null`) the floating signature hint.
  */
 export const setSignatureHintEffect = StateEffect.define<Tooltip | null>();
 
+// Bound the scan so large cells stay cheap on every keystroke.
+const MAX_LINES_BACK = 20;
+
+/**
+ * Whether the cursor is still inside the anchored call (just inside its `(`).
+ *
+ * Anchor-relative paren scan, bounded to {@link MAX_LINES_BACK} lines.
+ * Good enough for hint dismissal — not a full parse (ignores strings/comments).
+ */
+function isCursorInsideAnchoredCall(options: {
+  state: EditorState;
+  anchor: number;
+  head: number;
+}): boolean {
+  const { state, anchor, head } = options;
+  if (head < anchor) {
+    return false;
+  }
+
+  const headLine = state.doc.lineAt(head).number;
+  const anchorLine = state.doc.lineAt(anchor).number;
+  const startLine = Math.max(anchorLine, headLine - MAX_LINES_BACK + 1);
+  const from = Math.max(anchor, state.doc.line(startLine).from);
+
+  // If the anchor is outside the bounded window, assume its `(` is still open.
+  const assumedOpen = from > anchor;
+  let balance = assumedOpen ? 1 : 0;
+  const iter = state.doc.iterRange(from, head);
+  for (;;) {
+    const { value, done } = iter.next();
+    if (done) {
+      break;
+    }
+    for (const char of value) {
+      if (char === "(") {
+        balance++;
+      } else if (char === ")") {
+        balance--;
+        const closed = assumedOpen ? balance <= 0 : balance < 0;
+        if (closed) {
+          return false;
+        }
+      }
+    }
+  }
+  return true;
+}
+
 /**
  * Wrap a tooltip so it renders like the completion popup's info box.
  *
@@ -34,13 +83,7 @@ export function asSignatureHint(tooltip: Tooltip): Tooltip {
  * Holds the floating "signature hint" shown after typing `(` or `,` inside a
  * call on the non-LSP (Jedi) completion path.
  *
- * The LSP path has its own signature help; this fills the gap for users
- * without a language server. The completion source (`pythonCompletionSource`)
- * drives it: it dispatches `setSignatureHintEffect` with the tooltip when the
- * backend returns a signature and with `null` otherwise. The hint is also
- * cleared when the cursor moves via a selection-only change (e.g. clicking
- * away or arrowing out of the call), and kept anchored across edits so it
- * doesn't flicker while a fresh result is in flight.
+ * The LSP path has its own signature help; this fills the gap for users without a language server.
  */
 export const signatureHintField = StateField.define<Tooltip | null>({
   create: () => null,
@@ -57,12 +100,36 @@ export const signatureHintField = StateField.define<Tooltip | null>({
     if (tr.selection && !tr.docChanged) {
       return null;
     }
-    // Keep the hint anchored across edits; the completion source refreshes or
-    // clears it as new results arrive.
+    // Dismiss once the cursor leaves the anchored call (e.g. the closing paren
+    // is typed). Otherwise keep the hint anchored across edits so it doesn't
+    // flicker while a fresh result is in flight; the completion source refreshes
+    // or clears it as results arrive.
     if (tr.docChanged) {
-      return { ...tooltip, pos: tr.changes.mapPos(tooltip.pos) };
+      const anchor = tr.changes.mapPos(tooltip.pos);
+      if (
+        !isCursorInsideAnchoredCall({
+          state: tr.state,
+          anchor,
+          head: tr.state.selection.main.head,
+        })
+      ) {
+        return null;
+      }
+      return { ...tooltip, pos: anchor };
     }
     return tooltip;
   },
   provide: (field) => showTooltip.from(field),
 });
+
+/**
+ * Dismiss the floating signature hint if one is showing.
+ * Returns `true` if a hint was dismissed.
+ */
+export function closeSignatureHint(view: EditorView): boolean {
+  if (view.state.field(signatureHintField, false)) {
+    view.dispatch({ effects: setSignatureHintEffect.of(null) });
+    return true;
+  }
+  return false;
+}

package/src/core/constants.ts

@@ -50,6 +50,12 @@ export const KnownQueryParams = {
    * If false, the chrome will be hidden.
    */
   showChrome: "show-chrome",
+  /**
+   * Override the display theme: `light`, `dark`, or `system`.
+   * Takes precedence over the notebook's saved `display.theme`.
+   * Ignored for embedded islands, which infer the theme from their host page.
+   */
+  theme: "theme",
 };
 
 /**

package/src/theme/__tests__/useTheme.test.ts

@@ -0,0 +1,68 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { afterEach, describe, expect, it } from "vitest";
+import { configOverridesAtom, userConfigAtom } from "@/core/config/config";
+import { defaultUserConfig } from "@/core/config/config-schema";
+import { store } from "@/core/state/jotai";
+import type { Theme } from "../useTheme";
+import { resolvedThemeAtom, visibleForTesting } from "../useTheme";
+
+const { themeFromQueryParam } = visibleForTesting;
+
+function setQuery(search: string): void {
+  window.history.replaceState({}, "", search === "" ? "/" : `/?${search}`);
+}
+
+function setConfigTheme(theme: Theme): void {
+  const config = defaultUserConfig();
+  store.set(userConfigAtom, {
+    ...config,
+    display: { ...config.display, theme },
+  });
+}
+
+afterEach(() => {
+  setQuery("");
+  store.set(userConfigAtom, defaultUserConfig());
+  store.set(configOverridesAtom, {});
+});
+
+describe("themeFromQueryParam", () => {
+  it.each(["light", "dark", "system"] as const)(
+    "returns the valid theme %s",
+    (theme) => {
+      setQuery(`theme=${theme}`);
+      expect(themeFromQueryParam()).toBe(theme);
+    },
+  );
+
+  it("returns undefined when the param is absent", () => {
+    setQuery("");
+    expect(themeFromQueryParam()).toBeUndefined();
+  });
+
+  it("returns undefined for an invalid value", () => {
+    setQuery("theme=blue");
+    expect(themeFromQueryParam()).toBeUndefined();
+  });
+});
+
+describe("resolvedThemeAtom with a theme query param", () => {
+  it("uses the saved config theme when no param is present", () => {
+    setConfigTheme("dark");
+    setQuery("");
+    expect(store.get(resolvedThemeAtom)).toBe("dark");
+  });
+
+  it("lets the query param override the saved config theme", () => {
+    setConfigTheme("light");
+    setQuery("theme=dark");
+    expect(store.get(resolvedThemeAtom)).toBe("dark");
+  });
+
+  it("falls back to the config theme for an invalid param value", () => {
+    setConfigTheme("dark");
+    setQuery("theme=blue");
+    expect(store.get(resolvedThemeAtom)).toBe("dark");
+  });
+});

package/src/theme/useTheme.ts

@@ -2,6 +2,7 @@
 
 import { atom, useAtomValue } from "jotai";
 import { resolvedMarimoConfigAtom } from "@/core/config/config";
+import { KnownQueryParams } from "@/core/constants";
 import { isIslands } from "@/core/islands/utils";
 import { store } from "@/core/state/jotai";
 
@@ -10,6 +11,16 @@ export type ResolvedTheme = "light" | "dark";
 
 export const THEMES: Theme[] = ["light", "dark", "system"];
 
+function themeFromQueryParam(): Theme | undefined {
+  if (typeof window === "undefined") {
+    return undefined;
+  }
+  const value = new URLSearchParams(window.location.search).get(
+    KnownQueryParams.theme,
+  );
+  return THEMES.includes(value as Theme) ? (value as Theme) : undefined;
+}
+
 const themeAtom = atom((get) => {
   // If it is islands, try a few ways to infer if it is dark mode.
   if (isIslands()) {
@@ -51,7 +62,7 @@ const themeAtom = atom((get) => {
     return "light";
   }
 
-  return get(resolvedMarimoConfigAtom).display.theme;
+  return themeFromQueryParam() ?? get(resolvedMarimoConfigAtom).display.theme;
 });
 
 const prefersDarkModeAtom = atom(false);
@@ -122,3 +133,7 @@ export function useTheme(): { theme: ResolvedTheme } {
   const theme = useAtomValue(resolvedThemeAtom, { store });
   return { theme };
 }
+
+export const visibleForTesting = {
+  themeFromQueryParam,
+};