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.

fix: merge new panels into saved localStorage layout on upgrade (#8351)

jacobcbeaudind71768e6e096
diff --git a/frontend/src/components/editor/chrome/__tests__/state.test.ts b/frontend/src/components/editor/chrome/__tests__/state.test.ts
new file mode 100644
index 0000000000..73ae56e409
--- /dev/null
+++ b/frontend/src/components/editor/chrome/__tests__/state.test.ts
@@ -0,0 +1,321 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { describe, expect, it } from "vitest";
+import { adaptForLocalStorage } from "@/utils/storage/jotai";
+import type { PanelLayout } from "../state";
+import { exportedForTesting } from "../state";
+
+const { mergePanelLayout } = exportedForTesting;
+
+describe("mergePanelLayout", () => {
+ // Exact localStorage value from SageMaker Studio that caused the bug:
+ // saved before Terminal was added, so "terminal" is absent from
+ // developerPanel and the tab never renders.
+ it("appends terminal to a pre-terminal-era saved layout", () => {
+ const saved: PanelLayout = {
+ sidebar: [
+ "files",
+ "variables",
+ "packages",
+ "ai",
+ "outline",
+ "documentation",
+ "dependencies",
+ ],
+ developerPanel: [
+ "errors",
+ "scratchpad",
+ "tracing",
+ "secrets",
+ "snippets",
+ "logs",
+ ],
+ };
+ expect(mergePanelLayout(saved)).toEqual({
+ sidebar: [
+ "files",
+ "variables",
+ "packages",
+ "ai",
+ "outline",
+ "documentation",
+ "dependencies",
+ ],
+ developerPanel: [
+ "errors",
+ "scratchpad",
+ "tracing",
+ "secrets",
+ "snippets",
+ "logs",
+ "terminal",
+ ],
+ });
+ });
+
+ it("appends new sidebar panels missing from saved layout", () => {
+ const saved: PanelLayout = {
+ sidebar: ["files", "variables"],
+ developerPanel: [
+ "errors",
+ "scratchpad",
+ "tracing",
+ "secrets",
+ "logs",
+ "terminal",
+ "snippets",
+ ],
+ };
+ expect(mergePanelLayout(saved)).toEqual({
+ sidebar: [
+ "files",
+ "variables",
+ "packages",
+ "ai",
+ "outline",
+ "documentation",
+ "dependencies",
+ ],
+ developerPanel: [
+ "errors",
+ "scratchpad",
+ "tracing",
+ "secrets",
+ "logs",
+ "terminal",
+ "snippets",
+ ],
+ });
+ });
+
+ it("appends new developer panel entries missing from saved layout", () => {
+ const saved: PanelLayout = {
+ sidebar: [
+ "files",
+ "variables",
+ "packages",
+ "ai",
+ "outline",
+ "documentation",
+ "dependencies",
+ ],
+ developerPanel: ["errors", "scratchpad", "tracing", "logs"],
+ };
+ expect(mergePanelLayout(saved)).toEqual({
+ sidebar: [
+ "files",
+ "variables",
+ "packages",
+ "ai",
+ "outline",
+ "documentation",
+ "dependencies",
+ ],
+ developerPanel: [
+ "errors",
+ "scratchpad",
+ "tracing",
+ "logs",
+ "secrets",
+ "terminal",
+ "snippets",
+ ],
+ });
+ });
+
+ it("does not duplicate panels already present", () => {
+ const saved: PanelLayout = {
+ sidebar: [
+ "files",
+ "variables",
+ "packages",
+ "ai",
+ "outline",
+ "documentation",
+ "dependencies",
+ ],
+ developerPanel: [
+ "errors",
+ "scratchpad",
+ "tracing",
+ "secrets",
+ "logs",
+ "terminal",
+ "snippets",
+ ],
+ };
+ expect(mergePanelLayout(saved)).toEqual({
+ sidebar: [
+ "files",
+ "variables",
+ "packages",
+ "ai",
+ "outline",
+ "documentation",
+ "dependencies",
+ ],
+ developerPanel: [
+ "errors",
+ "scratchpad",
+ "tracing",
+ "secrets",
+ "logs",
+ "terminal",
+ "snippets",
+ ],
+ });
+ });
+
+ it("preserves panels the user moved between sections", () => {
+ const saved: PanelLayout = {
+ sidebar: ["files"],
+ developerPanel: ["errors", "variables"],
+ };
+ expect(mergePanelLayout(saved)).toEqual({
+ sidebar: [
+ "files",
+ "packages",
+ "ai",
+ "outline",
+ "documentation",
+ "dependencies",
+ ],
+ developerPanel: [
+ "errors",
+ "variables",
+ "scratchpad",
+ "tracing",
+ "secrets",
+ "logs",
+ "terminal",
+ "snippets",
+ ],
+ });
+ });
+
+ it("handles empty saved layout", () => {
+ const saved: PanelLayout = {
+ sidebar: [],
+ developerPanel: [],
+ };
+ expect(mergePanelLayout(saved)).toEqual({
+ sidebar: [
+ "files",
+ "variables",
+ "packages",
+ "ai",
+ "outline",
+ "documentation",
+ "dependencies",
+ ],
+ developerPanel: [
+ "errors",
+ "scratchpad",
+ "tracing",
+ "secrets",
+ "logs",
+ "terminal",
+ "snippets",
+ ],
+ });
+ });
+});
+
+describe("panelLayoutStorage integration", () => {
+ it("merges missing panels when reading from localStorage", () => {
+ // Simulate the exact SageMaker bug: stale layout in localStorage
+ const staleLayout: PanelLayout = {
+ sidebar: [
+ "files",
+ "variables",
+ "packages",
+ "ai",
+ "outline",
+ "documentation",
+ "dependencies",
+ ],
+ developerPanel: [
+ "errors",
+ "scratchpad",
+ "tracing",
+ "secrets",
+ "snippets",
+ "logs",
+ ],
+ };
+
+ // Mock localStorage with the stale value
+ const mockStorage: Storage = {
+ length: 1,
+ key: () => null,
+ clear: () => undefined,
+ removeItem: () => undefined,
+ setItem: () => undefined,
+ getItem: (key: string) => {
+ if (key === "marimo:panel-layout") {
+ return JSON.stringify(staleLayout);
+ }
+ return null;
+ },
+ };
+
+ const storage = adaptForLocalStorage<PanelLayout, PanelLayout>({
+ toSerializable: (v) => v,
+ fromSerializable: (saved) => mergePanelLayout(saved),
+ storage: mockStorage,
+ });
+
+ // This is what atomWithStorage calls on init
+ const defaultValue: PanelLayout = {
+ sidebar: [],
+ developerPanel: [],
+ };
+ const result = storage.getItem("marimo:panel-layout", defaultValue);
+
+ expect(result).toEqual({
+ sidebar: [
+ "files",
+ "variables",
+ "packages",
+ "ai",
+ "outline",
+ "documentation",
+ "dependencies",
+ ],
+ developerPanel: [
+ "errors",
+ "scratchpad",
+ "tracing",
+ "secrets",
+ "snippets",
+ "logs",
+ "terminal",
+ ],
+ });
+ });
+
+ it("returns default when localStorage is empty", () => {
+ const mockStorage: Storage = {
+ length: 0,
+ key: () => null,
+ clear: () => undefined,
+ removeItem: () => undefined,
+ setItem: () => undefined,
+ getItem: () => null,
+ };
+
+ const storage = adaptForLocalStorage<PanelLayout, PanelLayout>({
+ toSerializable: (v) => v,
+ fromSerializable: (saved) => mergePanelLayout(saved),
+ storage: mockStorage,
+ });
+
+ const defaultValue: PanelLayout = {
+ sidebar: ["files"],
+ developerPanel: ["errors"],
+ };
+ const result = storage.getItem("marimo:panel-layout", defaultValue);
+
+ // Should return the initialValue (default) since nothing in storage
+ expect(result).toEqual(defaultValue);
+ });
+});
diff --git a/frontend/src/components/editor/chrome/state.ts b/frontend/src/components/editor/chrome/state.ts
index 0c5958fd4d..dfd04bd634 100644
--- a/frontend/src/components/editor/chrome/state.ts
+++ b/frontend/src/components/editor/chrome/state.ts
@@ -5,7 +5,7 @@ import { atomWithStorage } from "jotai/utils";
import { z } from "zod";
import { store } from "@/core/state/jotai";
import { createReducerAndAtoms } from "@/utils/createReducer";
-import { jotaiJsonStorage } from "@/utils/storage/jotai";
+import { adaptForLocalStorage } from "@/utils/storage/jotai";
import { ZodLocalStorage } from "@/utils/storage/typed";
import type { PanelSection, PanelType } from "./types";
import { PANELS } from "./types";
@@ -35,10 +35,34 @@ const DEFAULT_PANEL_LAYOUT: PanelLayout = {
).map((p) => p.type),
};
+/**
+ * Merge saved layout with current defaults so new panels added in later
+ * versions are appended to their default section. Panels the user has
+ * moved between sections are left where the user put them.
+ */
+function mergePanelLayout(saved: PanelLayout): PanelLayout {
+ const allSaved = new Set([...saved.sidebar, ...saved.developerPanel]);
+ return {
+ sidebar: [
+ ...saved.sidebar,
+ ...DEFAULT_PANEL_LAYOUT.sidebar.filter((p) => !allSaved.has(p)),
+ ],
+ developerPanel: [
+ ...saved.developerPanel,
+ ...DEFAULT_PANEL_LAYOUT.developerPanel.filter((p) => !allSaved.has(p)),
+ ],
+ };
+}
+
+const panelLayoutStorage = adaptForLocalStorage<PanelLayout, PanelLayout>({
+ toSerializable: (v) => v,
+ fromSerializable: (saved) => mergePanelLayout(saved),
+});
+
export const panelLayoutAtom = atomWithStorage<PanelLayout>(
"marimo:panel-layout",
DEFAULT_PANEL_LAYOUT,
- jotaiJsonStorage,
+ panelLayoutStorage,
{ getOnInit: true },
);
@@ -181,4 +205,5 @@ export const exportedForTesting = {
reducer,
createActions,
initialState,
+ mergePanelLayout,
};