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.

perf(frontend): progressively mount cell editors in the editor view (#9904)

Kiran Gadhave0ab87cbdc000
diff --git a/frontend/src/__tests__/setup.ts b/frontend/src/__tests__/setup.ts
index 901f8fc480..4dce4f9ece 100644
--- a/frontend/src/__tests__/setup.ts
+++ b/frontend/src/__tests__/setup.ts
@@ -20,6 +20,22 @@ globalThis.ResizeObserver ??= class {
}
} as never;
+// mock implementation because jsdom doesn't support IntersectionObserver
+globalThis.IntersectionObserver ??= class {
+ observe(_target: Element) {
+ /* noop */
+ }
+ unobserve(_target: Element) {
+ /* noop */
+ }
+ disconnect() {
+ /* noop */
+ }
+ takeRecords() {
+ return [];
+ }
+} as never;
+
// Global setup for all tests
beforeEach(() => {
// Reset all mocks before each test
diff --git a/frontend/src/components/editor/cell/code/cell-editor.tsx b/frontend/src/components/editor/cell/code/cell-editor.tsx
index 0a69c265c0..e489f9c2e0 100644
--- a/frontend/src/components/editor/cell/code/cell-editor.tsx
+++ b/frontend/src/components/editor/cell/code/cell-editor.tsx
@@ -2,8 +2,9 @@
import { historyField } from "@codemirror/commands";
import { EditorState, StateEffect } from "@codemirror/state";
import { EditorView, ViewPlugin } from "@codemirror/view";
+import { useIntersectionObserver } from "@uidotdev/usehooks";
import { useAtom, useAtomValue } from "jotai";
-import React, { memo, useEffect, useMemo, useRef } from "react";
+import React, { memo, useEffect, useMemo, useRef, useState } from "react";
import useEvent from "react-use-event-hook";
import { Button } from "@/components/ui/button";
import { DelayMount } from "@/components/utils/delay-mount";
@@ -14,6 +15,7 @@ import { usePendingDeleteService } from "@/core/cells/pending-delete-service";
import type { CellData, CellRuntimeState } from "@/core/cells/types";
import { setupCodeMirror } from "@/core/codemirror/cm";
import { acceptCompletionOnEnterAtom } from "@/core/codemirror/completion/accept-on-enter-atom";
+import { editorMountScheduler } from "@/core/codemirror/editor-mount-scheduler";
import {
getInitialLanguageAdapter,
languageAdapterState,
@@ -45,6 +47,7 @@ import {
} from "../../navigation/navigation";
import { useDeleteCellCallback } from "../useDeleteCell";
import { useSplitCellCallback } from "../useSplitCell";
+import { CodePlaceholder } from "./code-placeholder";
import { LanguageToggles } from "./language-toggle";
export interface CellEditorProps
@@ -405,38 +408,45 @@ const CellEditorInternal = ({
// Clear the serialized state so that we don't re-create the editor next time
cellActions.clearSerializedEditorState({ cellId });
});
+ const [isEditorMounted, setIsEditorMounted] = useState(
+ serializedEditorState !== null,
+ );
+ // Build the editor. Deserialize eagerly; otherwise queue an async build so
+ // large notebooks stay responsive while editors come online progressively.
useEffect(() => {
- if (serializedEditorState === null) {
- if (editorViewRef.current === null) {
- handleInitializeEditor();
- } else {
- // If the editor already exists, reconfigure it with the new extensions.
- handleReconfigureEditor();
- }
- } else {
- handleDeserializeEditor();
+ if (editorViewRef.current !== null) {
+ setIsEditorMounted(true);
+ return;
}
-
- if (
- editorViewRef.current !== null &&
- editorViewParentRef &&
- editorViewParentRef.current !== null
- ) {
- // Always replace the children in case the editor view was re-created.
- editorViewParentRef.current.replaceChildren(editorViewRef.current.dom);
+ if (serializedEditorState !== null) {
+ handleDeserializeEditor();
+ setIsEditorMounted(true);
+ return;
}
+ editorMountScheduler.request(cellId, () => {
+ if (editorViewRef.current !== null) {
+ return;
+ }
+ handleInitializeEditor();
+ setIsEditorMounted(true);
+ });
+ return () => editorMountScheduler.cancel(cellId);
}, [
- handleInitializeEditor,
- handleReconfigureEditor,
- handleDeserializeEditor,
+ cellId,
editorViewRef,
- editorViewParentRef,
+ handleDeserializeEditor,
+ handleInitializeEditor,
serializedEditorState,
- // Props to trigger reconfiguration
- extensions,
]);
+ useEffect(() => {
+ if (editorViewRef.current === null) {
+ return;
+ }
+ handleReconfigureEditor();
+ }, [handleReconfigureEditor, extensions, editorViewRef]);
+
// Destroy the editor when the component is unmounted
useEffect(() => {
const ev = editorViewRef.current;
@@ -445,6 +455,23 @@ const CellEditorInternal = ({
};
}, [editorViewRef]);
+ // Prioritize building this cell's editor when it scrolls into view, so the
+ // visible region fills in first instead of waiting for the top-to-bottom
+ // queue. The margin builds cells just before they reach the viewport.
+ const [intersectionRef, intersection] = useIntersectionObserver({
+ rootMargin: "300px 0px",
+ });
+ useEffect(() => {
+ if (isEditorMounted) {
+ return;
+ }
+ if (intersection?.isIntersecting) {
+ editorMountScheduler.prioritize(cellId);
+ } else {
+ editorMountScheduler.deprioritize(cellId);
+ }
+ }, [isEditorMounted, intersection?.isIntersecting, cellId]);
+
const navigationProps = useCellEditorNavigationProps(cellId, editorViewRef);
let editorClassName = "";
@@ -489,14 +516,22 @@ const CellEditorInternal = ({
runCell={handleRunCell}
outputArea={outputArea}
>
- <div className="relative w-full" {...navigationProps}>
- <CellCodeMirrorEditor
- className={editorClassName}
- editorView={editorViewRef.current}
- ref={editorViewParentRef}
- hidden={hidden}
- showHiddenCode={showHiddenCode}
- />
+ <div
+ className="relative w-full"
+ ref={intersectionRef}
+ {...navigationProps}
+ >
+ {isEditorMounted ? (
+ <CellCodeMirrorEditor
+ className={editorClassName}
+ editorView={editorViewRef.current}
+ ref={editorViewParentRef}
+ hidden={hidden}
+ showHiddenCode={showHiddenCode}
+ />
+ ) : (
+ <CodePlaceholder code={code} className={editorClassName} />
+ )}
{!hidden && showLanguageToggles && (
<div className="absolute top-1 right-5">
<LanguageToggles
diff --git a/frontend/src/components/editor/cell/code/code-placeholder.css b/frontend/src/components/editor/cell/code/code-placeholder.css
new file mode 100644
index 0000000000..fcf98895a8
--- /dev/null
+++ b/frontend/src/components/editor/cell/code/code-placeholder.css
@@ -0,0 +1,17 @@
+.mo-code-placeholder {
+ --mo-skeleton-bar: color-mix(in srgb, var(--muted), var(--foreground) 18%);
+ cursor: default;
+ padding: 4px 10px;
+ font-size: var(--cm-font-size, 0.875rem);
+}
+
+.mo-code-placeholder-line {
+ display: flex;
+ align-items: center;
+ height: 1.5em;
+}
+
+.mo-code-placeholder-bar {
+ height: 0.7em;
+ background-color: var(--mo-skeleton-bar);
+}
diff --git a/frontend/src/components/editor/cell/code/code-placeholder.tsx b/frontend/src/components/editor/cell/code/code-placeholder.tsx
new file mode 100644
index 0000000000..a799ca4287
--- /dev/null
+++ b/frontend/src/components/editor/cell/code/code-placeholder.tsx
@@ -0,0 +1,46 @@
+import "./code-placeholder.css";
+import { Skeleton } from "@/components/ui/skeleton";
+import { cn } from "@/utils/cn";
+
+interface CodePlaceholderProps {
+ code: string;
+ className?: string;
+}
+
+// Bound the rendered bars so a very long cell does not create excessive nodes.
+const MAX_LINES = 50;
+const MIN_LINE_WIDTH_CH = 4;
+const MAX_LINE_WIDTH_CH = 60;
+
+function getLineWidthCh(length: number): number {
+ return Math.min(MAX_LINE_WIDTH_CH, Math.max(MIN_LINE_WIDTH_CH, length));
+}
+
+/**
+ * Stand-in shown while a cell's CodeMirror editor has not been built yet.
+ * one skeleton bar per code line, so the final render doesn't cause a big jump.
+ */
+export const CodePlaceholder = ({ code, className }: CodePlaceholderProps) => {
+ const lines = code.split("\n", MAX_LINES);
+ return (
+ <div
+ className={cn("cm", "mo-code-placeholder", className)}
+ data-testid="cell-editor-placeholder"
+ aria-hidden={true}
+ >
+ {lines.map((line, index) => {
+ const length = line.trimEnd().length;
+ return (
+ <div key={index} className="mo-code-placeholder-line">
+ {length > 0 && (
+ <Skeleton
+ className="mo-code-placeholder-bar"
+ style={{ width: `${getLineWidthCh(length)}ch` }}
+ />
+ )}
+ </div>
+ );
+ })}
+ </div>
+ );
+};
diff --git a/frontend/src/core/cells/scrollCellIntoView.ts b/frontend/src/core/cells/scrollCellIntoView.ts
index a0b109cdaf..7cdb061288 100644
--- a/frontend/src/core/cells/scrollCellIntoView.ts
+++ b/frontend/src/core/cells/scrollCellIntoView.ts
@@ -7,6 +7,7 @@ import {
import type { CellHandle } from "@/components/editor/notebook-cell";
import { retryWithTimeout } from "@/utils/timeout";
import { Logger } from "../../utils/Logger";
+import { editorMountScheduler } from "../codemirror/editor-mount-scheduler";
import { scrollActiveLineIntoView } from "../codemirror/extensions";
import { goToVariableDefinition } from "../codemirror/go-to-definition/commands";
import { getCellEditorView } from "./cells";
@@ -48,6 +49,9 @@ export function focusAndScrollCellIntoView({
// https://github.com/marimo-team/marimo/issues/2940
tryFocus(element);
} else {
+ // Build this cell's editor now if it is still queued, so focus can land in
+ // it instead of the placeholder.
+ editorMountScheduler.promote(cellId);
const editor = cell.current?.editorView;
if (!editor) {
Logger.warn("scrollCellIntoView: editor not found", cellId);
diff --git a/frontend/src/core/codemirror/__tests__/editor-mount-scheduler.test.ts b/frontend/src/core/codemirror/__tests__/editor-mount-scheduler.test.ts
new file mode 100644
index 0000000000..14fd54ec09
--- /dev/null
+++ b/frontend/src/core/codemirror/__tests__/editor-mount-scheduler.test.ts
@@ -0,0 +1,142 @@
+import { describe, expect, it } from "vitest";
+import { createEditorMountScheduler } from "../editor-mount-scheduler";
+
+function makeManualSchedule() {
+ let pending: (() => void) | null = null;
+ const schedule = (cb: () => void) => {
+ pending = cb;
+ };
+ const flush = () => {
+ const cb = pending;
+ pending = null;
+ cb?.();
+ };
+ return { schedule, flush, hasPending: () => pending !== null };
+}
+
+describe("createEditorMountScheduler", () => {
+ it("builds one queued editor per tick in FIFO order, rescheduling between", () => {
+ const { schedule, flush, hasPending } = makeManualSchedule();
+ const built: string[] = [];
+ const s = createEditorMountScheduler(schedule);
+ s.request("a", () => built.push("a"));
+ s.request("b", () => built.push("b"));
+ flush();
+ expect(built).toEqual(["a"]);
+ expect(hasPending()).toBe(true);
+ flush();
+ expect(built).toEqual(["a", "b"]);
+ });
+
+ it("stops rescheduling once the queue is empty", () => {
+ const { schedule, flush, hasPending } = makeManualSchedule();
+ const built: string[] = [];
+ const s = createEditorMountScheduler(schedule);
+ s.request("a", () => built.push("a"));
+ flush();
+ expect(built).toEqual(["a"]);
+ expect(hasPending()).toBe(false);
+ });
+
+ it("promote builds immediately and removes from the queue", () => {
+ const { schedule, flush } = makeManualSchedule();
+ const built: string[] = [];
+ const s = createEditorMountScheduler(schedule);
+ s.request("a", () => built.push("a"));
+ s.request("b", () => built.push("b"));
+ s.promote("b");
+ expect(built).toEqual(["b"]);
+ flush();
+ expect(built).toEqual(["b", "a"]);
+ });
+
+ it("cancel prevents a queued build", () => {
+ const { schedule, flush } = makeManualSchedule();
+ const built: string[] = [];
+ const s = createEditorMountScheduler(schedule);
+ s.request("a", () => built.push("a"));
+ s.cancel("a");
+ flush();
+ expect(built).toEqual([]);
+ });
+
+ it("builds prioritized cells before earlier-queued ones", () => {
+ const { schedule, flush } = makeManualSchedule();
+ const built: string[] = [];
+ const s = createEditorMountScheduler(schedule);
+ s.request("a", () => built.push("a"));
+ s.request("b", () => built.push("b"));
+ s.request("c", () => built.push("c"));
+ s.prioritize("c");
+ flush();
+ flush();
+ flush();
+ expect(built).toEqual(["c", "a", "b"]);
+ });
+
+ it("builds multiple prioritized cells in prioritization order, then FIFO", () => {
+ const { schedule, flush } = makeManualSchedule();
+ const built: string[] = [];
+ const s = createEditorMountScheduler(schedule);
+ s.request("a", () => built.push("a"));
+ s.request("b", () => built.push("b"));
+ s.request("c", () => built.push("c"));
+ s.request("d", () => built.push("d"));
+ s.prioritize("d");
+ s.prioritize("b");
+ flush();
+ flush();
+ flush();
+ flush();
+ expect(built).toEqual(["d", "b", "a", "c"]);
+ });
+
+ it("ignores prioritize for a cell that is not queued", () => {
+ const { schedule, flush } = makeManualSchedule();
+ const built: string[] = [];
+ const s = createEditorMountScheduler(schedule);
+ s.request("a", () => built.push("a"));
+ s.prioritize("not-queued");
+ flush();
+ expect(built).toEqual(["a"]);
+ });
+
+ it("deprioritize reverts a cell to FIFO order without dropping it", () => {
+ const { schedule, flush } = makeManualSchedule();
+ const built: string[] = [];
+ const s = createEditorMountScheduler(schedule);
+ s.request("a", () => built.push("a"));
+ s.request("b", () => built.push("b"));
+ s.prioritize("b");
+ s.deprioritize("b");
+ flush();
+ flush();
+ expect(built).toEqual(["a", "b"]);
+ });
+
+ it("keeps draining the queue after a build throws", () => {
+ const { schedule, flush } = makeManualSchedule();
+ const built: string[] = [];
+ const s = createEditorMountScheduler(schedule);
+ s.request("a", () => {
+ throw new Error("boom");
+ });
+ s.request("b", () => built.push("b"));
+ expect(() => flush()).toThrow("boom");
+ flush();
+ expect(built).toEqual(["b"]);
+ });
+
+ it("cancel removes a prioritized cell", () => {
+ const { schedule, flush } = makeManualSchedule();
+ const built: string[] = [];
+ const s = createEditorMountScheduler(schedule);
+ s.request("a", () => built.push("a"));
+ s.request("b", () => built.push("b"));
+ s.prioritize("b");
+ s.cancel("b");
+ flush();
+ flush();
+ expect(built).toEqual(["a"]);
+ });
+});
diff --git a/frontend/src/core/codemirror/editor-mount-scheduler.ts b/frontend/src/core/codemirror/editor-mount-scheduler.ts
new file mode 100644
index 0000000000..d321d68379
--- /dev/null
+++ b/frontend/src/core/codemirror/editor-mount-scheduler.ts
@@ -0,0 +1,100 @@
+import {
+ scheduleTask as defaultScheduleTask,
+ type ScheduleTaskFn,
+} from "@/utils/schedule-task";
+
+type BuildFn = () => void;
+
+export interface EditorMountScheduler {
+ /** Queue a cell's editor build to run on a future task. */
+ request(cellId: string, build: BuildFn): void;
+ /** Build a queued cell's editor synchronously, right now (e.g. on focus). */
+ promote(cellId: string): void;
+ /**
+ * Mark a queued cell to build ahead of un-prioritized ones, keeping the
+ * one-build-per-task pacing (e.g. when the cell scrolls into view).
+ */
+ prioritize(cellId: string): void;
+ /** Drop a cell's prioritized mark, reverting it to plain FIFO order. */
+ deprioritize(cellId: string): void;
+ /** Remove a cell's queued build entirely. */
+ cancel(cellId: string): void;
+}
+
+/**
+ * Drains a FIFO queue of editor builds, one per macrotask, so constructing many
+ * CodeMirror instances never blocks the main thread in a single long task. The
+ * scheduler yields between every build to keep the page responsive. Cells can
+ * be prioritized (e.g. when they scroll into view) to jump ahead of the queue
+ * without breaking the one-build-per-macrotask pacing.
+ */
+export function createEditorMountScheduler(
+ scheduleTask: ScheduleTaskFn = defaultScheduleTask,
+): EditorMountScheduler {
+ const queue = new Map<string, BuildFn>();
+ const priority = new Set<string>();
+ let isProcessingScheduled = false;
+
+ function scheduleProcessing(): void {
+ if (isProcessingScheduled || queue.size === 0) {
+ return;
+ }
+ isProcessingScheduled = true;
+ scheduleTask(processNext);
+ }
+
+ // Prioritized cells first, in the order they were prioritized; then FIFO.
+ function nextCellId(): string | undefined {
+ for (const cellId of priority) {
+ if (queue.has(cellId)) {
+ return cellId;
+ }
+ priority.delete(cellId);
+ }
+ return queue.keys().next().value;
+ }
+
+ function processNext(): void {
+ isProcessingScheduled = false;
+ try {
+ const cellId = nextCellId();
+ if (cellId !== undefined) {
+ const build = queue.get(cellId);
+ queue.delete(cellId);
+ priority.delete(cellId);
+ build?.();
+ }
+ } finally {
+ scheduleProcessing();
+ }
+ }
+
+ return {
+ request(cellId, build) {
+ queue.set(cellId, build);
+ scheduleProcessing();
+ },
+ promote(cellId) {
+ const build = queue.get(cellId);
+ if (build) {
+ queue.delete(cellId);
+ priority.delete(cellId);
+ build();
+ }
+ },
+ prioritize(cellId) {
+ if (queue.has(cellId)) {
+ priority.add(cellId);
+ }
+ },
+ deprioritize(cellId) {
+ priority.delete(cellId);
+ },
+ cancel(cellId) {
+ queue.delete(cellId);
+ priority.delete(cellId);
+ },
+ };
+}
+
+export const editorMountScheduler = createEditorMountScheduler();
diff --git a/frontend/src/utils/schedule-task.ts b/frontend/src/utils/schedule-task.ts
new file mode 100644
index 0000000000..60931ca99c
--- /dev/null
+++ b/frontend/src/utils/schedule-task.ts
@@ -0,0 +1,70 @@
+/**
+ * Schedules `callback` to run as a fresh task once the current task finishes,
+ * letting the browser paint and handle input in between. Used to spread heavy
+ * work across the event loop instead of blocking it in one long task.
+ */
+export type ScheduleTaskFn = (callback: () => void) => void;
+
+/**
+ * Picks the best available "yield to the event loop" primitive, preferring
+ * ones that impose no artificial delay between tasks:
+ *
+ * 1. `scheduler.postTask` — the purpose-built Prioritized Task Scheduling API.
+ * `user-visible` runs promptly while still yielding to user-blocking input.
+ * 2. `MessageChannel` — a plain macrotask with no minimum-delay clamp (nested
+ * `setTimeout` is floored at ~4ms by the spec, which would add up over many
+ * tasks).
+ * 3. `setTimeout` — universal fallback; correct, just clamped when nested.
+ *
+ * The backend is chosen once, at module load, since it cannot change within a
+ * session.
+ */
+// `scheduler` (the Prioritized Task Scheduling API) is not in this repo's
+// lib.dom typings, so it is feature-detected behind this minimal cast.
+interface PostTaskScheduler {
+ postTask: (
+ callback: () => void,
+ options?: { priority?: "user-blocking" | "user-visible" | "background" },
+ ) => Promise<unknown>;
+}
+
+function createScheduleTask(): ScheduleTaskFn {
+ const scheduler = (globalThis as { scheduler?: PostTaskScheduler }).scheduler;
+ if (typeof scheduler?.postTask === "function") {
+ return (cb) => {
+ // postTask rejects when the callback throws. Rethrow on a fresh task so a
+ // thrown callback surfaces as an uncaught error, matching the
+ // MessageChannel/setTimeout backends, instead of an unhandledrejection.
+ void scheduler
+ .postTask(cb, { priority: "user-visible" })
+ .catch((error) => {
+ setTimeout(() => {
+ throw error;
+ });
+ });
+ };
+ }
+
+ if (typeof MessageChannel === "function") {
+ // Both ports live on this thread and no data is sent: posting a message is
+ // just the cheapest way to enqueue a macrotask that yields for paint. The
+ // queue lets multiple callbacks be in flight at once (one per message).
+ const pending: Array<() => void> = [];
+ const channel = new MessageChannel();
+ channel.port1.onmessage = () => {
+ pending.shift()?.();
+ };
+
+ return (cb) => {
+ pending.push(cb);
+ channel.port2.postMessage(null);
+ };
+ }
+
+ return (cb) => {
+ setTimeout(cb, 0);
+ };
+}
+
+/** Shared task scheduler using the best primitive this environment offers. */
+export const scheduleTask = createScheduleTask();