Skip to content

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.

3.3 KB
Raw Blame
/* 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;
}