@marimo-team/frontend 0.23.14-dev2 → 0.23.14-dev21

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

@@ -0,0 +1,94 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { EditorState } from "@codemirror/state";
+import { EditorView, type Tooltip } from "@codemirror/view";
+import { describe, expect, it } from "vitest";
+import {
+  asSignatureHint,
+  setSignatureHintEffect,
+  signatureHintField,
+} from "../signature-hint";
+
+function fakeTooltip(pos: number): Tooltip {
+  return {
+    pos,
+    above: true,
+    create: () => ({ dom: document.createElement("div") }),
+  };
+}
+
+function stateWithHint(doc: string, pos: number): EditorState {
+  const state = EditorState.create({
+    doc,
+    extensions: [signatureHintField],
+  });
+  return state.update({ effects: setSignatureHintEffect.of(fakeTooltip(pos)) })
+    .state;
+}
+
+describe("signatureHintField", () => {
+  it("starts empty", () => {
+    const state = EditorState.create({ extensions: [signatureHintField] });
+    expect(state.field(signatureHintField)).toBeNull();
+  });
+
+  it("shows a tooltip when the effect is dispatched", () => {
+    const state = stateWithHint("plt.plot(", 9);
+    expect(state.field(signatureHintField)?.pos).toBe(9);
+  });
+
+  it("clears the tooltip when the effect dispatches null", () => {
+    let state = stateWithHint("plt.plot(", 9);
+    state = state.update({
+      effects: setSignatureHintEffect.of(null),
+    }).state;
+    expect(state.field(signatureHintField)).toBeNull();
+  });
+
+  it("dismisses the tooltip on a selection-only change", () => {
+    let state = stateWithHint("plt.plot(x)", 9);
+    state = state.update({ selection: { anchor: 0 } }).state;
+    expect(state.field(signatureHintField)).toBeNull();
+  });
+
+  it("keeps and re-anchors the tooltip across edits", () => {
+    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;
+    expect(state.field(signatureHintField)?.pos).toBe(11);
+  });
+});
+
+describe("asSignatureHint", () => {
+  it("nests the content so descendant styling applies", () => {
+    const content = document.createElement("span");
+    content.classList.add("mo-cm-tooltip", "docs-documentation");
+    const base: Tooltip = {
+      pos: 0,
+      create: () => ({ dom: content, resize: false }),
+    };
+
+    const view = new EditorView({ state: EditorState.create({}) });
+    const { dom } = asSignatureHint(base).create(view);
+
+    // Outer wrapper carries the tooltip sizing class...
+    expect(dom.classList.contains("mo-cm-tooltip")).toBe(true);
+    // ...and the documentation content is a descendant (not the same node),
+    // so `.cm-tooltip .docs-documentation` padding/font rules match.
+    expect(dom).not.toBe(content);
+    expect(dom.querySelector(".docs-documentation")).toBe(content);
+
+    view.destroy();
+  });
+
+  it("preserves other tooltip fields", () => {
+    const base: Tooltip = {
+      pos: 5,
+      above: true,
+      create: () => ({ dom: document.createElement("span"), resize: false }),
+    };
+    const wrapped = asSignatureHint(base);
+    expect(wrapped.pos).toBe(5);
+    expect(wrapped.above).toBe(true);
+  });
+});

package/src/core/codemirror/completion/completer.ts

@@ -9,6 +9,7 @@ import { documentationAtom } from "@/core/documentation/state";
 import { store } from "@/core/state/jotai";
 import { Logger } from "../../../utils/Logger";
 import { AUTOCOMPLETER, Autocompleter } from "./Autocompleter";
+import { asSignatureHint, setSignatureHintEffect } from "./signature-hint";
 
 /**
  * Completion source for Python, using Jedi.
@@ -36,10 +37,12 @@ export const pythonCompletionSource: CompletionSource = async (
     cellId: cellId,
   });
   if (!result) {
+    context.view?.dispatch({ effects: setSignatureHintEffect.of(null) });
     return null;
   }
 
-  // If it is a tooltip, show it as a Tooltip instead of a completion
+  // If it is a tooltip (e.g. a signature after `(` or `,`), show it as a
+  // Tooltip instead of a completion.
   const tooltip = Autocompleter.asHoverTooltip({
     position: context.pos,
     message: result,
@@ -50,6 +53,14 @@ export const pythonCompletionSource: CompletionSource = async (
       documentation: tooltip.html ?? null,
     });
   }
+  // Surface the signature as a floating hint near the cursor (the LSP path has
+  // its own signature help), and clear any stale hint when we instead have a
+  // real completion list.
+  context.view?.dispatch({
+    effects: setSignatureHintEffect.of(
+      tooltip ? asSignatureHint(tooltip) : null,
+    ),
+  });
   if (tooltip) {
     return null;
   }

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

@@ -0,0 +1,68 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { StateEffect, StateField } from "@codemirror/state";
+import { showTooltip, type Tooltip } from "@codemirror/view";
+
+/**
+ * Effect to set (or clear, with `null`) the floating signature hint.
+ */
+export const setSignatureHintEffect = StateEffect.define<Tooltip | null>();
+
+/**
+ * Wrap a tooltip so it renders like the completion popup's info box.
+ *
+ * CodeMirror adds `cm-tooltip` directly to the DOM node returned by `create`,
+ * so the documentation content ends up on the same element as `cm-tooltip`.
+ * Our styling for padding/font (`.cm-tooltip .docs-documentation`) is a
+ * descendant selector, so we nest the content one level deeper to make it
+ * apply — mirroring how CodeMirror nests completion info inside its own
+ * wrapper. The outer `mo-cm-tooltip` class picks up the shared tooltip sizing.
+ */
+export function asSignatureHint(tooltip: Tooltip): Tooltip {
+  return {
+    ...tooltip,
+    create: (view) => {
+      const { dom: content, ...rest } = tooltip.create(view);
+      const dom = document.createElement("div");
+      dom.classList.add("mo-cm-tooltip");
+      dom.append(content);
+      return { ...rest, dom };
+    },
+  };
+}
+
+/**
+ * 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.
+ */
+export const signatureHintField = StateField.define<Tooltip | null>({
+  create: () => null,
+  update(tooltip, tr) {
+    for (const effect of tr.effects) {
+      if (effect.is(setSignatureHintEffect)) {
+        return effect.value;
+      }
+    }
+    if (!tooltip) {
+      return null;
+    }
+    // Cursor moved without editing (click / arrow key): dismiss the hint.
+    if (tr.selection && !tr.docChanged) {
+      return null;
+    }
+    // Keep the hint anchored across edits; the completion source refreshes or
+    // clears it as new results arrive.
+    if (tr.docChanged) {
+      return { ...tooltip, pos: tr.changes.mapPos(tooltip.pos) };
+    }
+    return tooltip;
+  },
+  provide: (field) => showTooltip.from(field),
+});

package/src/core/codemirror/language/languages/python.ts

@@ -31,6 +31,7 @@ import { Logger } from "@/utils/Logger";
 import { once } from "@/utils/once";
 import { cellActionsState } from "../../cells/state";
 import { pythonCompletionSource } from "../../completion/completer";
+import { signatureHintField } from "../../completion/signature-hint";
 import type { PlaceholderType } from "../../config/types";
 import { FederatedLanguageServerClient } from "../../lsp/federated-lsp";
 import { createLspMarkdownRenderer } from "../../lsp/markdown-renderer";
@@ -376,10 +377,15 @@ export class PythonLanguageAdapter implements LanguageAdapter<{}> {
         ];
       }
 
-      return autocompletion({
-        ...autocompleteOptions,
-        override: [pythonCompletionSource],
-      });
+      return [
+        autocompletion({
+          ...autocompleteOptions,
+          override: [pythonCompletionSource],
+        }),
+        // The Jedi path has no built-in signature help; show a floating hint
+        // fed by `pythonCompletionSource` (the LSP path handles this itself).
+        signatureHintField,
+      ];
     };
 
     return [

package/src/core/codemirror/utils.ts

@@ -2,6 +2,7 @@
 import type { EditorState, Transaction } from "@codemirror/state";
 import type { EditorView, ViewUpdate } from "@codemirror/view";
 import { getCM } from "@replit/codemirror-vim";
+import type { ReactCodeMirrorRef } from "@uiw/react-codemirror";
 
 export function isAtStartOfEditor(ev: { state: EditorState }) {
   const main = ev.state.selection.main;
@@ -37,6 +38,20 @@ export function moveToEndOfEditor(ev: EditorView | undefined) {
   });
 }
 
+/** We delay the focus and move to end of the editor until React has rendered the prefilled value. */
+export function focusInputAndMoveToEnd(
+  ref: React.RefObject<ReactCodeMirrorRef | null>,
+) {
+  requestAnimationFrame(() => {
+    const view = ref.current?.view;
+    if (!view) {
+      return;
+    }
+    view.focus();
+    moveToEndOfEditor(view);
+  });
+}
+
 export function isInVimMode(ev: EditorView): boolean {
   return getCM(ev)?.state.vim != null;
 }

package/src/core/edit-app.tsx

@@ -13,6 +13,7 @@ import { AppHeader } from "@/components/editor/header/app-header";
 import { FilenameForm } from "@/components/editor/header/filename-form";
 import { MultiCellActionToolbar } from "@/components/editor/navigation/multi-cell-action-toolbar";
 import { ViewerBanner } from "@/components/editor/viewer-banner";
+import { ProgressiveBoundary } from "@/components/lifecycle/ProgressiveBoundary";
 import { cn } from "@/utils/cn";
 import { Paths } from "@/utils/paths";
 import { AppContainer } from "../components/editor/app-container";
@@ -64,7 +65,6 @@ export const EditApp: React.FC<AppProps> = ({
     useCellActions();
   const viewState = useAtomValue(viewStateAtom);
   const numColumns = useAtomValue(numColumnsAtom);
-  const hasCells = useAtomValue(hasCellsAtom);
   const filename = useFilename();
   const setLastSavedNotebook = useSetAtom(lastSavedNotebookAtom);
   const { sendComponentValues, sendInterrupt } = useRequestClient();
@@ -181,13 +181,16 @@ export const EditApp: React.FC<AppProps> = ({
 
         <ViewerBanner />
 
-        {/* Don't render until we have a single cell */}
-        {hasCells && (
+        {/* Don't render until we have a single cell. NotStartedConnectionAlert
+            still covers the "no remote runtime started" prompt. */}
+        <ProgressiveBoundary
+          requires={hasCellsAtom}
+          fallback={<NotStartedConnectionAlert />}
+        >
           <CellsRenderer appConfig={appConfig} mode={viewState.mode}>
             {editableCellsArray}
           </CellsRenderer>
-        )}
-        {!hasCells && <NotStartedConnectionAlert />}
+        </ProgressiveBoundary>
       </AppContainer>
       <MultiCellActionToolbar />
       {!hideControls && (

package/src/core/errors/errors.ts

@@ -6,6 +6,7 @@ import type { AiCompletionCell } from "../ai/state";
 import type { CellId } from "../cells/ids";
 import type { MarimoError } from "../kernel/messages";
 import { wrapInFunction } from "./utils";
+import { store } from "../state/jotai";
 
 interface AIFix {
   setAiCompletionCell: (opts: AiCompletionCell) => void;
@@ -84,7 +85,7 @@ export function getAutoFixes(
         description: "Fix the SQL statement",
         fixType: "ai",
         onFix: async (ctx) => {
-          const datasourceContext = getDatasourceContext(ctx.cellId);
+          const datasourceContext = getDatasourceContext(ctx.cellId, store);
           let initialPrompt = `Fix the SQL statement: ${error.msg}.`;
           if (datasourceContext) {
             initialPrompt += `\nDatabase schema: ${datasourceContext}`;

package/src/core/lifecycle/__tests__/render-policy.test.ts

@@ -0,0 +1,247 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { visibleForTesting } from "../render-policy";
+
+const { computeRenderPolicy } = visibleForTesting;
+
+const originalHref = window.location.href;
+function setSearch(search: string) {
+  window.history.replaceState(null, "", `/${search}`);
+}
+
+describe("computeRenderPolicy", () => {
+  it("shows code in edit mode", () => {
+    const policy = computeRenderPolicy({
+      mode: "edit",
+      showAppCode: false, // ignored in edit mode
+      hasCells: true,
+      hasCachedOutputs: false,
+      allCellsIdle: false,
+    });
+    expect(policy.showCode).toBe(true);
+  });
+
+  it("hides code in present mode regardless of config", () => {
+    const policy = computeRenderPolicy({
+      mode: "present",
+      showAppCode: true,
+      hasCells: true,
+      hasCachedOutputs: true,
+      allCellsIdle: false,
+    });
+    expect(policy.showCode).toBe(false);
+  });
+
+  it("respects showAppCode in read mode", () => {
+    expect(
+      computeRenderPolicy({
+        mode: "read",
+        showAppCode: true,
+        hasCells: true,
+        hasCachedOutputs: false,
+        allCellsIdle: false,
+      }).showCode,
+    ).toBe(true);
+
+    expect(
+      computeRenderPolicy({
+        mode: "read",
+        showAppCode: false,
+        hasCells: true,
+        hasCachedOutputs: false,
+        allCellsIdle: false,
+      }).showCode,
+    ).toBe(false);
+  });
+
+  it("reports showCachedOutputs when cells and cached outputs are present", () => {
+    expect(
+      computeRenderPolicy({
+        mode: "read",
+        showAppCode: false,
+        hasCells: true,
+        hasCachedOutputs: true,
+        allCellsIdle: false,
+      }).showCachedOutputs,
+    ).toBe(true);
+  });
+
+  it("does not report showCachedOutputs when there are no cells", () => {
+    expect(
+      computeRenderPolicy({
+        mode: "read",
+        showAppCode: false,
+        hasCells: false,
+        hasCachedOutputs: true,
+        allCellsIdle: false,
+      }).showCachedOutputs,
+    ).toBe(false);
+  });
+
+  it("only reports showCachedOutputs for real outputs, not an idle notebook", () => {
+    // Regression guard: `showCachedOutputs` must stay honest even when the
+    // notebook is settled with no outputs (that only affects `canPaint`).
+    expect(
+      computeRenderPolicy({
+        mode: "read",
+        showAppCode: false,
+        hasCells: true,
+        hasCachedOutputs: false,
+        allCellsIdle: true,
+      }).showCachedOutputs,
+    ).toBe(false);
+  });
+});
+
+describe("computeRenderPolicy — read-mode code visibility", () => {
+  beforeEach(() => {
+    setSearch("");
+  });
+
+  afterEach(() => {
+    window.history.replaceState(null, "", originalHref);
+  });
+
+  it("hides code when the server stripped sources (?include-code=false)", () => {
+    setSearch("?include-code=false");
+    const policy = computeRenderPolicy({
+      mode: "read",
+      showAppCode: true, // config would show code, but sources are stripped
+      hasCells: true,
+      hasCachedOutputs: false,
+      allCellsIdle: false,
+    });
+    expect(policy.showCode).toBe(false);
+    // With no code, no outputs, and still running, there is nothing to paint.
+    expect(policy.canPaint).toBe(false);
+  });
+
+  it("include-code=false still paints when cached outputs exist", () => {
+    setSearch("?include-code=false");
+    expect(
+      computeRenderPolicy({
+        mode: "read",
+        showAppCode: true,
+        hasCells: true,
+        hasCachedOutputs: true,
+        allCellsIdle: false,
+      }).canPaint,
+    ).toBe(true);
+  });
+});
+
+describe("computeRenderPolicy.canPaint", () => {
+  it("is false when no cells exist, even if all (zero) cells are vacuously idle", () => {
+    expect(
+      computeRenderPolicy({
+        mode: "read",
+        showAppCode: true,
+        hasCells: false,
+        hasCachedOutputs: false,
+        allCellsIdle: true,
+      }).canPaint,
+    ).toBe(false);
+  });
+
+  it("is true in edit mode whenever cells exist", () => {
+    expect(
+      computeRenderPolicy({
+        mode: "edit",
+        showAppCode: false,
+        hasCells: true,
+        hasCachedOutputs: false,
+        allCellsIdle: false,
+      }).canPaint,
+    ).toBe(true);
+  });
+
+  it("is true in read mode when code is visible", () => {
+    expect(
+      computeRenderPolicy({
+        mode: "read",
+        showAppCode: true,
+        hasCells: true,
+        hasCachedOutputs: false,
+        allCellsIdle: false,
+      }).canPaint,
+    ).toBe(true);
+  });
+
+  it("is false in headless read mode while the notebook is still running with no outputs", () => {
+    expect(
+      computeRenderPolicy({
+        mode: "read",
+        showAppCode: false,
+        hasCells: true,
+        hasCachedOutputs: false,
+        allCellsIdle: false,
+      }).canPaint,
+    ).toBe(false);
+  });
+
+  it("is true in headless read mode with cached outputs", () => {
+    expect(
+      computeRenderPolicy({
+        mode: "read",
+        showAppCode: false,
+        hasCells: true,
+        hasCachedOutputs: true,
+        allCellsIdle: false,
+      }).canPaint,
+    ).toBe(true);
+  });
+
+  it("is true in headless read mode for a settled notebook with no outputs", () => {
+    // A notebook that ran to completion producing no outputs must still paint
+    // (empty) rather than sit on a spinner — parity with the pre-framework
+    // `hasAnyOutputAtom` idle fallback.
+    expect(
+      computeRenderPolicy({
+        mode: "read",
+        showAppCode: false,
+        hasCells: true,
+        hasCachedOutputs: false,
+        allCellsIdle: true,
+      }).canPaint,
+    ).toBe(true);
+  });
+
+  // In present mode `showCode` is always false, so `canPaint` rides entirely
+  // on cached outputs / a settled notebook.
+  it("is true in present mode with cached outputs", () => {
+    expect(
+      computeRenderPolicy({
+        mode: "present",
+        showAppCode: true,
+        hasCells: true,
+        hasCachedOutputs: true,
+        allCellsIdle: false,
+      }).canPaint,
+    ).toBe(true);
+  });
+
+  it("is false in present mode while still running with no outputs", () => {
+    expect(
+      computeRenderPolicy({
+        mode: "present",
+        showAppCode: true,
+        hasCells: true,
+        hasCachedOutputs: false,
+        allCellsIdle: false,
+      }).canPaint,
+    ).toBe(false);
+  });
+
+  it("is true in present mode for a settled notebook with no outputs", () => {
+    expect(
+      computeRenderPolicy({
+        mode: "present",
+        showAppCode: true,
+        hasCells: true,
+        hasCachedOutputs: false,
+        allCellsIdle: true,
+      }).canPaint,
+    ).toBe(true);
+  });
+});

package/src/core/lifecycle/render-policy.ts

@@ -0,0 +1,125 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { atom } from "jotai";
+import { hasCellsAtom, notebookAtom } from "../cells/cells";
+import { isOutputEmpty } from "../cells/outputs";
+import { KnownQueryParams } from "../constants";
+import { showCodeInRunModeAtom } from "../meta/state";
+import { type AppMode, initialModeAtom } from "../mode";
+import { hasQueryParam } from "@/utils/urls";
+
+export interface RenderPolicy {
+  /** False in `present` mode, and in `read` mode when the user has opted to hide code. */
+  showCode: boolean;
+  /** True only when there are real, non-empty cached outputs to display. */
+  showCachedOutputs: boolean;
+  /**
+   * Whether the current view has anything to paint without waiting on the
+   * runtime:
+   * - In edit/home/gallery mode, this is `hasCells` — the editor renders the
+   *   cell skeleton even when output is empty.
+   * - In read/present mode with code visible, the cell source is enough.
+   * - In headless read mode (code hidden), we need either cached outputs or a
+   *   settled notebook (all cells idle) — a completed but output-less notebook
+   *   is still "done" and shouldn't strand on an infinite spinner.
+   */
+  canPaint: boolean;
+}
+
+function readCodeVisibility(
+  mode: AppMode | undefined,
+  showAppCode: boolean,
+): boolean {
+  if (mode === "edit" || mode === "home" || mode === "gallery") {
+    return true;
+  }
+  if (mode === "present") {
+    return false;
+  }
+  // read mode (or undefined). If `marimo run` stripped the sources
+  // (`--include-code` off), there is no code to show regardless of any other
+  // signal — mirror `core/meta/code-visibility.ts` so the two don't drift.
+  if (hasQueryParam(KnownQueryParams.includeCode, "false")) {
+    return false;
+  }
+  // Otherwise the URL `show-code` param wins, then the view config.
+  if (hasQueryParam(KnownQueryParams.showCode, "false")) {
+    return false;
+  }
+  if (hasQueryParam(KnownQueryParams.showCode, "true")) {
+    return true;
+  }
+  return showAppCode;
+}
+
+function computeRenderPolicy(input: {
+  mode: AppMode | undefined;
+  showAppCode: boolean;
+  hasCells: boolean;
+  hasCachedOutputs: boolean;
+  /**
+   * True when every cell is idle. A settled notebook is paintable even with no
+   * visible outputs — otherwise a completed but output-less notebook viewed in
+   * headless read mode would strand on an infinite spinner. Mirrors the
+   * pre-framework `hasAnyOutputAtom` idle fallback.
+   */
+  allCellsIdle: boolean;
+}): RenderPolicy {
+  const showCode = readCodeVisibility(input.mode, input.showAppCode);
+  const showCachedOutputs = input.hasCells && input.hasCachedOutputs;
+  const canPaint =
+    input.hasCells && (showCode || showCachedOutputs || input.allCellsIdle);
+
+  return { showCode, showCachedOutputs, canPaint };
+}
+
+/**
+ * Both cell-runtime facts the render policy needs, computed in a single pass
+ * over `cellRuntime`:
+ * - `hasCachedOutputs`: any cell has a non-empty output.
+ * - `allCellsIdle`: every cell's status is idle — nothing queued or running.
+ *   Vacuously true for an empty notebook, so `canPaint` still gates on
+ *   `hasCells`.
+ *
+ * Fan out to two boolean selector atoms below so `renderPolicyAtom` only
+ * recomputes when one of the booleans actually flips, not on every notebook
+ * update.
+ */
+const cellRuntimeSummaryAtom = atom((get) => {
+  let hasCachedOutputs = false;
+  let allCellsIdle = true;
+  for (const runtime of Object.values(get(notebookAtom).cellRuntime)) {
+    if (!isOutputEmpty(runtime.output)) {
+      hasCachedOutputs = true;
+    }
+    if (runtime.status !== "idle") {
+      allCellsIdle = false;
+    }
+  }
+  return { hasCachedOutputs, allCellsIdle };
+});
+
+const hasCachedOutputsAtom = atom(
+  (get) => get(cellRuntimeSummaryAtom).hasCachedOutputs,
+);
+
+const allCellsIdleAtom = atom(
+  (get) => get(cellRuntimeSummaryAtom).allCellsIdle,
+);
+
+export const renderPolicyAtom = atom<RenderPolicy>((get) =>
+  computeRenderPolicy({
+    mode: get(initialModeAtom),
+    showAppCode: get(showCodeInRunModeAtom),
+    hasCells: get(hasCellsAtom),
+    hasCachedOutputs: get(hasCachedOutputsAtom),
+    allCellsIdle: get(allCellsIdleAtom),
+  }),
+);
+
+/** Sugar over `renderPolicyAtom.canPaint`. */
+export const canPaintAtom = atom((get) => get(renderPolicyAtom).canPaint);
+
+export const visibleForTesting = {
+  computeRenderPolicy,
+};