A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
/* Copyright 2026 Marimo. All rights reserved. */
import { atom, useAtomValue } from "jotai";
import { KnownQueryParams } from "@/core/constants";
import { isIslands } from "@/core/islands/utils";
import { assertExists } from "@/utils/assertExists";
import { invariant } from "@/utils/invariant";
import type { CellId } from "./cells/ids";
import { store } from "./state/jotai";
/**
* This is the internal mode.
* - `read`: A user is reading the notebook. Cannot switch to edit/present mode.
* - `edit`: A user is editing the notebook. Can switch to present mode.
* - `present`: A user is presenting the notebook, it looks like read mode but with some editing features. Cannot switch to present mode.
* - `home`: A user is in the home page.
* - `gallery`: A user is in the gallery page.
*/
export type AppMode = "read" | "edit" | "present" | "home" | "gallery";
export function getInitialAppMode(): Exclude<AppMode, "present"> {
const initialMode = store.get(initialModeAtom);
assertExists(initialMode, "internal-error: initial mode not found");
invariant(
initialMode !== "present",
"internal-error: initial mode cannot be 'present'",
);
return initialMode;
}
export function toggleAppMode(mode: AppMode): AppMode {
// Can't switch to present mode.
if (mode === "read" || mode === "home" || mode === "gallery") {
return mode;
}
return mode === "edit" ? "present" : "edit";
}
/**
* View state for the app.
*/
interface ViewState {
/**
* The mode of the app: read/edit/present
*/
mode: AppMode;
/**
* A cell ID to anchor scrolling to when toggling between presenting and
* editing views
*/
cellAnchor: CellId | null;
}
export async function runDuringPresentMode(
fn: () => void | Promise<void>,
): Promise<void> {
const state = store.get(viewStateAtom);
if (state.mode !== "edit") {
await fn();
return;
}
store.set(viewStateAtom, { ...state, mode: "present" });
try {
// Wait 100ms to allow the page to render
await new Promise((resolve) => setTimeout(resolve, 100));
// Wait 2 frames
await new Promise((resolve) => requestAnimationFrame(resolve));
await new Promise((resolve) => requestAnimationFrame(resolve));
await fn();
} finally {
store.set(viewStateAtom, state);
}
}
export const viewStateAtom = atom<ViewState>({
mode: isIslands() ? "read" : ("not-set" as AppMode),
cellAnchor: null,
});
export const initialModeAtom = atom<AppMode | undefined>(undefined);
/**
* Whether the current page hosts a notebook, and so connects to a kernel.
* False for non-notebook pages (home, gallery), which are served without a
* session.
*/
export function isNotebookPage(): boolean {
const mode = store.get(initialModeAtom);
return mode !== "home" && mode !== "gallery";
}
export const kioskModeAtom = atom<boolean>(false);
/**
* Whether installing packages is allowed in the current view. False in read
* mode, since end-users of a deployed notebook cannot mutate its environment.
*/
export function useInstallAllowed(): boolean {
const { mode } = useAtomValue(viewStateAtom);
const kioskMode = useAtomValue(kioskModeAtom);
const kioskRequested =
new URLSearchParams(window.location.search).get(KnownQueryParams.kiosk) ===
"true";
return mode !== "read" && !kioskMode && !kioskRequested;
}