@marimo-team/islands 0.25.3-dev191 → 0.25.3-dev193

package/src/core/cells/editor.ts

@@ -0,0 +1,82 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/** What only this browser knows about cells: hidden code showing for now, and editor state to restore. */
+
+import { atom, useAtomValue } from "jotai";
+import { useMemo } from "react";
+import type { SerializedEditorState } from "../codemirror/types";
+import type { CellId } from "./ids";
+
+/**
+ * Hidden cells whose code is showing for now: a cell being edited, one just
+ * created, or one just made hidden. Blurring the cell hides it again.
+ */
+export const shownHiddenCodeAtom = atom<ReadonlySet<CellId>>(new Set<CellId>());
+
+export const useShowsHiddenCode = (cellId: CellId) =>
+  useAtomValue(
+    useMemo(
+      () => atom((get) => get(shownHiddenCodeAtom).has(cellId)),
+      [cellId],
+    ),
+  );
+
+/** Whether a cell's code is hidden on the page. */
+export function isCodeHidden(
+  hideCode: boolean | undefined,
+  shown: ReadonlySet<CellId>,
+  cellId: CellId,
+): boolean {
+  return Boolean(hideCode) && !shown.has(cellId);
+}
+
+export const showHiddenCodeAtom = atom(
+  null,
+  (_get, set, { cellId }: { cellId: CellId }): void => {
+    set(shownHiddenCodeAtom, (cells) => new Set([...cells, cellId]));
+  },
+);
+
+/** Hide a cell's code again. Returns whether it was showing. */
+export const hideShownCodeAtom = atom(
+  null,
+  (get, set, { cellId }: { cellId: CellId }): boolean => {
+    if (!get(shownHiddenCodeAtom).has(cellId)) {
+      return false;
+    }
+    set(shownHiddenCodeAtom, (cells) => {
+      const next = new Set(cells);
+      next.delete(cellId);
+      return next;
+    });
+    return true;
+  },
+);
+
+/**
+ * Editor state for cells about to mount again, such as a cell undo brings
+ * back. The editor takes its entry when it mounts, and deleting the cell
+ * drops it.
+ */
+export const restoredEditorStatesAtom = atom<
+  ReadonlyMap<CellId, SerializedEditorState>
+>(new Map<CellId, SerializedEditorState>());
+
+export const useRestoredEditorState = (cellId: CellId) =>
+  useAtomValue(
+    useMemo(
+      () => atom((get) => get(restoredEditorStatesAtom).get(cellId) ?? null),
+      [cellId],
+    ),
+  );
+
+export const takeRestoredEditorStateAtom = atom(
+  null,
+  (_get, set, { cellId }: { cellId: CellId }): void => {
+    set(restoredEditorStatesAtom, (states) => {
+      const next = new Map(states);
+      next.delete(cellId);
+      return next;
+    });
+  },
+);

package/src/core/cells/layout.ts

@@ -0,0 +1,152 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/** The cells as they appear on the page: by column, with folded sections hidden. */
+
+import { atom, useAtomValue } from "jotai";
+import type { CellColumnId } from "@/utils/id-tree";
+import { findCollapseRange } from "../dom/outline";
+import { cellIdsAtom, cellOutlinesAtom } from "./cells";
+import type { CellId } from "./ids";
+import type { Outline } from "./outline";
+
+/** The headers whose sections the user folded. Only this browser knows. */
+export const collapsedAtom = atom<ReadonlySet<CellId>>(new Set<CellId>());
+
+export interface LayoutColumn {
+  readonly id: CellColumnId;
+  /** Every cell of the column, in order. */
+  readonly ids: readonly CellId[];
+  /** The cells on the page: those no fold hides. */
+  readonly visible: readonly CellId[];
+  /**
+   * Each folded header and the cells it hides, nested sections included. A
+   * folded header with nothing under it yet has an empty fold.
+   */
+  readonly folds: ReadonlyMap<CellId, readonly CellId[]>;
+}
+
+export interface Layout {
+  readonly columns: readonly LayoutColumn[];
+}
+
+/**
+ * The cells each folded header hides. A section runs from its header to the
+ * cell before the next header of the same or a higher level, so a folded
+ * header inside a folded section is hidden along with its own section.
+ */
+export function foldSections(
+  ids: readonly CellId[],
+  outlines: (Outline | null)[],
+  collapsed: ReadonlySet<CellId>,
+): Map<CellId, readonly CellId[]> {
+  const folds = new Map<CellId, readonly CellId[]>();
+  ids.forEach((id, index) => {
+    const outline = outlines[index];
+    if (!collapsed.has(id) || !outline || outline.items.length === 0) {
+      return;
+    }
+    const range = findCollapseRange(index, outlines);
+    if (range === null) {
+      return;
+    }
+    folds.set(id, ids.slice(index + 1, range[1] + 1));
+  });
+  return folds;
+}
+
+export function deriveLayout(
+  columns: ReadonlyArray<{ id: CellColumnId; ids: readonly CellId[] }>,
+  outlineOf: (id: CellId) => Outline | null,
+  collapsed: ReadonlySet<CellId>,
+): Layout {
+  return {
+    columns: columns.map(({ id, ids }) => {
+      const folds = foldSections(ids, ids.map(outlineOf), collapsed);
+      const hidden = new Set([...folds.values()].flat());
+      return { id, ids, visible: ids.filter((c) => !hidden.has(c)), folds };
+    }),
+  };
+}
+
+/**
+ * The layout of the notebook's cells.
+ *
+ * TODO(MO-8028): Order and columns come from the reducer's tree until the
+ * arrange family edits the document; then they derive from the document and
+ * the column ids this browser keeps. Outlines come from executions later.
+ */
+export const layoutAtom = atom((get): Layout => {
+  const outlines = get(cellOutlinesAtom);
+  return deriveLayout(
+    get(cellIdsAtom)
+      .getColumns()
+      .map((column) => ({ id: column.id, ids: column.inOrderIds })),
+    (id) => outlines[id] ?? null,
+    get(collapsedAtom),
+  );
+});
+
+export const useLayout = () => useAtomValue(layoutAtom);
+
+export function findColumn(
+  layout: Layout,
+  columnId: CellColumnId,
+): LayoutColumn | undefined {
+  return layout.columns.find((column) => column.id === columnId);
+}
+
+/** The column holding `id`. Throws for a cell the layout does not have. */
+export function columnOf(layout: Layout, id: CellId): LayoutColumn {
+  const column = layout.columns.find((column) => column.ids.includes(id));
+  if (column === undefined) {
+    throw new Error(`Cell ${id} is not in the layout`);
+  }
+  return column;
+}
+
+/** The cells a folded header hides, or undefined when `id` is not a folded header. */
+export function foldOf(
+  layout: Layout,
+  id: CellId,
+): readonly CellId[] | undefined {
+  for (const column of layout.columns) {
+    const fold = column.folds.get(id);
+    if (fold !== undefined) {
+      return fold;
+    }
+  }
+  return undefined;
+}
+
+/** The headers whose folds hide `id`. */
+export function foldsHiding(layout: Layout, id: CellId): CellId[] {
+  const column = layout.columns.find((column) => column.ids.includes(id));
+  if (column === undefined) {
+    return [];
+  }
+  return [...column.folds]
+    .filter(([, hidden]) => hidden.includes(id))
+    .map(([header]) => header);
+}
+
+/**
+ * The folded headers whose sections a cell without a heading would fall
+ * into, placed right after `id`: those hiding `id`, and `id` itself when it
+ * is a folded header. A section runs until the next heading, so a cell
+ * placed after the last cell of a fold is still inside it.
+ */
+export function foldsAfter(layout: Layout, id: CellId): CellId[] {
+  const hiding = foldsHiding(layout, id);
+  return foldOf(layout, id) === undefined ? hiding : [...hiding, id];
+}
+
+/** The visible cell `offset` places from `id` in its column, if there is one. */
+export function visibleNeighbor(
+  layout: Layout,
+  id: CellId,
+  offset: -1 | 1,
+): CellId | undefined {
+  const { visible } = columnOf(layout, id);
+  const index = visible.indexOf(id);
+  return index === -1 ? undefined : visible[index + offset];
+}

package/src/core/cells/session.ts

@@ -1,17 +1,19 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
+/** Read the notebook a page was served with: its cells as a host snapshot, and their outputs. */
+
+import type * as Protocol from "@marimo-team/client/protocol";
 import type * as api from "@marimo-team/marimo-api";
 import { mergeArray } from "@/utils/edit-distance";
-import { MultiColumn } from "@/utils/id-tree";
 import { Logger } from "@/utils/Logger";
 import { parseOutline } from "../dom/outline";
-import type { NotebookState } from "./cells";
+import type { StaticNotebookSnapshot } from "../transports/static";
 import { CellId, SETUP_CELL_ID } from "./ids";
-import {
-  type CellData,
-  type CellRuntimeState,
-  createCellRuntimeState,
-} from "./types";
+import { DEFAULT_CELL_NAME } from "./names";
+import { type CellRuntimeState, createCellRuntimeState } from "./types";
+
+/** The identity of a snapshot the page carries. A host's own stream replaces it. */
+const EMBEDDED = "embedded";
 
 // Constants
 const DEFAULT_TIMESTAMP = 0;
@@ -143,7 +145,7 @@ function createEmptyNotebookCell(): NotebookCell {
   return {
     id: CellId.create(),
     name: EMPTY_STRING,
-    code: EMPTY_STRING,
+    code: null,
     code_hash: null,
     config: {
       column: null,
@@ -163,24 +165,22 @@ function createEmptySessionCell(): SessionCell {
   };
 }
 
-function createCellDataFromNotebook(
-  cellId: CellId,
-  notebookCell: NotebookCell,
-): CellData {
+/** The cell as a host would describe it. A snapshot never changes, so its etags only need to be distinct. */
+function cellRecord(cellId: CellId, cell: NotebookCell): Protocol.Cell {
   return {
     id: cellId,
-    name: notebookCell.name ?? EMPTY_STRING,
-    code: notebookCell.code ?? EMPTY_STRING,
-    edited: false,
-    lastCodeRun: null,
-    lastExecutionTime: null,
+    notebook_id: EMBEDDED,
+    code: cell.code,
+    name: cell.name || DEFAULT_CELL_NAME,
     config: {
-      column: notebookCell.config?.column ?? null,
-      disabled: notebookCell.config?.disabled ?? false,
-      hide_code: notebookCell.config?.hide_code ?? false,
-      expand_output: notebookCell.config?.expand_output ?? false,
+      column: cell.config?.column ?? null,
+      disabled: cell.config?.disabled ?? false,
+      hide_code: cell.config?.hide_code ?? false,
+      expand_output: cell.config?.expand_output ?? false,
     },
-    serializedEditorState: null,
+    etag: `${EMBEDDED}:${cellId}`,
+    code_hash: cell.code_hash ?? `${EMBEDDED}:${cellId}:code`,
+    version: 1,
   };
 }
 
@@ -278,45 +278,68 @@ function createCellRuntimeFromSession(
   };
 }
 
-export function notebookStateFromSession(
-  session: api.Session["NotebookSessionV1"] | null | undefined,
-  notebook: api.Notebook["NotebookV1"] | null | undefined,
-): NotebookState | null {
-  // Merge session and notebook cells using edit distance
+/**
+ * Read the session and notebook a page embeds.
+ *
+ * The cells become a host snapshot the replica starts from, and the session's
+ * outputs seed each cell's runtime until the kernel speaks. Null when the page
+ * carries no cells.
+ */
+export function readExport({
+  session,
+  notebook,
+  filename,
+  appConfig,
+}: {
+  session: api.Session["NotebookSessionV1"] | null | undefined;
+  notebook: api.Notebook["NotebookV1"] | null | undefined;
+  filename: string | null;
+  appConfig: Record<string, unknown>;
+}): {
+  snapshot: StaticNotebookSnapshot | null;
+  cellRuntime: Record<CellId, CellRuntimeState>;
+} {
   const { cellIds, sessionCellData, notebookCellData } =
     mergeSessionAndNotebookCells(session, notebook);
-
   if (cellIds.length === 0) {
-    return null;
+    return { snapshot: null, cellRuntime: {} };
   }
 
-  const cellData: Record<CellId, CellData> = {};
+  const cells: Protocol.Cell[] = [];
   const cellRuntime: Record<CellId, CellRuntimeState> = {};
-
-  // Process each cell
   for (const cellId of cellIds) {
-    const sessionCell = sessionCellData.get(cellId);
-    const notebookCell = notebookCellData.get(cellId);
-
-    // Create cell data from notebook if available
-    if (notebookCell) {
-      cellData[cellId] = createCellDataFromNotebook(cellId, notebookCell);
-    }
-
-    // Create cell runtime
-    // This needs always be created even if there is no session cell
-    // in order to display the cell in the correct state
-    cellRuntime[cellId] = createCellRuntimeFromSession(sessionCell);
+    cells.push(
+      cellRecord(
+        cellId,
+        notebookCellData.get(cellId) ?? createEmptyNotebookCell(),
+      ),
+    );
+    cellRuntime[cellId] = createCellRuntimeFromSession(
+      sessionCellData.get(cellId),
+    );
   }
 
   return {
-    cellIds: MultiColumn.from([cellIds]),
-    cellData: cellData,
-    cellRuntime: cellRuntime,
-    cellHandles: {},
-    history: [],
-    scrollKey: null,
-    cellLogs: [],
-    untouchedNewCells: new Set(),
+    snapshot: {
+      notebook: {
+        id: EMBEDDED,
+        project_id: EMBEDDED,
+        path: filename,
+        name: filename ?? EMPTY_STRING,
+        updated_at: null,
+      },
+      document: {
+        notebook_id: EMBEDDED,
+        order: cellIds,
+        app_config: appConfig,
+        etag: `${EMBEDDED}:document`,
+        saved_etag: `${EMBEDDED}:document`,
+        order_etag: `${EMBEDDED}:order`,
+        app_config_etag: `${EMBEDDED}:app_config`,
+        version: 1,
+      },
+      cells,
+    },
+    cellRuntime,
   };
 }

package/src/core/cells/types.ts

@@ -1,7 +1,6 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
 import type { Milliseconds, Seconds } from "@/utils/time";
-import type { SerializedEditorState } from "../codemirror/types";
 import type { OutputMessage } from "../kernel/messages";
 import type { CellConfig, RuntimeState } from "../network/types";
 import type { CellId } from "./ids";
@@ -31,7 +30,6 @@ export function createCell({
   lastExecutionTime = null,
   edited = false,
   config,
-  serializedEditorState = null,
 }: Partial<CellData> & { id: CellId }): CellData {
   return {
     id: id,
@@ -46,7 +44,6 @@ export function createCell({
     edited: edited,
     lastCodeRun: lastCodeRun,
     lastExecutionTime: lastExecutionTime,
-    serializedEditorState: serializedEditorState,
   };
 }
 
@@ -97,8 +94,6 @@ export interface CellData {
   lastExecutionTime: number | null;
   /** cell configuration */
   config: CellConfig;
-  /** serialized state of the underlying editor */
-  serializedEditorState: SerializedEditorState | null;
 }
 
 export interface CellRuntimeState {

package/src/core/cells/utils.ts

@@ -79,11 +79,13 @@ export function getUndoLabel(state: NotebookState): string {
 }
 
 /**
- * Get the status of the descendants of the given cell.
+ * Summarize the run state of the given descendants, whether any is stale,
+ * errored, or running.
  */
-export function getDescendantsStatus(state: NotebookState, cellId: CellId) {
-  const column = state.cellIds.findWithId(cellId);
-  const descendants = column.getDescendants(cellId);
+export function getDescendantsStatus(
+  state: NotebookState,
+  descendants: readonly CellId[],
+) {
   const stale = descendants.some(
     (id) => state.cellRuntime[id]?.staleInputs || state.cellData[id]?.edited,
   );

package/src/core/config/__tests__/app-config.test.ts

@@ -0,0 +1,64 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { atom, createStore } from "jotai";
+import { describe, expect, it } from "vitest";
+import { partial } from "@/__mocks__/partial";
+import type { Document, NotebookReplica } from "@/core/notebook/replica";
+import { activeNotebookReplicaAtom } from "@/core/session/active-notebook";
+import { appConfigAtom, pageAppConfigAtom } from "../config";
+
+function document(app_config: Record<string, unknown>, version = 1): Document {
+  return {
+    revision: {
+      notebook_id: "nb",
+      order: [],
+      app_config,
+      etag: `etag-${version}`,
+      saved_etag: null,
+      order_etag: "order",
+      app_config_etag: "config",
+      version,
+    },
+    cells: new Map(),
+  };
+}
+
+function connect(store: ReturnType<typeof createStore>, current: Document) {
+  store.set(
+    activeNotebookReplicaAtom,
+    partial<NotebookReplica>({ documentAtom: atom(current) }, "replica"),
+  );
+}
+
+describe("appConfigAtom", () => {
+  it("reads the page's config until the host document arrives", () => {
+    const store = createStore();
+    expect(store.get(appConfigAtom).width).toBe("compact");
+    store.set(pageAppConfigAtom, { width: "full" });
+    expect(store.get(appConfigAtom).width).toBe("full");
+    connect(store, document({ width: "compact" }));
+    expect(store.get(appConfigAtom).width).toBe("compact");
+  });
+
+  it("fills what the host document leaves out with Python's defaults", () => {
+    const store = createStore();
+    store.set(pageAppConfigAtom, { width: "full" });
+    // The document carries only the options that differ from the defaults.
+    connect(store, document({}));
+    expect(store.get(appConfigAtom)).toEqual({
+      width: "compact",
+      auto_download: [],
+      sql_output: "auto",
+    });
+  });
+
+  it("keeps the same object while the record is unchanged", () => {
+    const store = createStore();
+    connect(store, document({ width: "full" }, 1));
+    const first = store.get(appConfigAtom);
+    connect(store, document({ width: "full" }, 2));
+    expect(store.get(appConfigAtom)).toBe(first);
+    connect(store, document({ width: "medium" }, 3));
+    expect(store.get(appConfigAtom).width).toBe("medium");
+  });
+});

package/src/core/config/__tests__/config-schema.test.ts

@@ -27,7 +27,7 @@ test("default AppConfig", () => {
     {
       "auto_download": [],
       "sql_output": "auto",
-      "width": "medium",
+      "width": "compact",
     }
   `);
 });

package/src/core/config/config-schema.ts

@@ -278,11 +278,15 @@ export const SqlOutputSchema = z
   .enum(VALID_SQL_OUTPUT_FORMATS)
   .prefault("auto");
 
+/**
+ * The notebook's app config. The defaults are Python's `_AppConfig` defaults,
+ * since the host document carries only what differs from them.
+ */
 export const AppConfigSchema = z
   .object({
     width: z
       .enum(VALID_APP_WIDTHS)
-      .prefault("medium")
+      .prefault("compact")
       .transform((width) => {
         if (width === "normal") {
           return "compact";
@@ -296,7 +300,7 @@ export const AppConfigSchema = z
     sql_output: SqlOutputSchema,
   })
   .prefault(() => ({
-    width: "medium" as const,
+    width: "compact" as const,
     auto_download: [],
     sql_output: "auto" as const,
   }));

package/src/core/config/config.ts

@@ -1,8 +1,11 @@
 /* Copyright 2026 Marimo. All rights reserved. */
+import { dequal } from "dequal";
 import { atom, useAtom, useAtomValue, useSetAtom } from "jotai";
+import { selectAtom } from "jotai/vanilla/utils";
 import { mergeWith } from "lodash-es";
 import { OverridingHotkeyProvider } from "../hotkeys/hotkeys";
 import { type Platform, resolvePlatform } from "../hotkeys/shortcuts";
+import { confirmedDocumentAtom } from "../session/active-notebook";
 import { store } from "../state/jotai";
 import {
   type AppConfig,
@@ -134,19 +137,30 @@ export function isAiFeatureEnabled(config: UserConfig) {
 }
 
 /**
- * Atom for storing the app config.
+ * The app config the page was served with, as the server wrote it.
+ *
+ * The host document carries the current one; this holds its place until
+ * that document arrives. It goes once every page carries its document.
  */
-export const appConfigAtom = atom<AppConfig>(parseAppConfig({}));
-
-/**
- * Returns the app config.
- */
-export function useAppConfig() {
-  return useAtom(appConfigAtom);
-}
-
-export function useSetAppConfig() {
-  return useSetAtom(appConfigAtom);
+export const pageAppConfigAtom = atom<unknown>({});
+
+/** The app config record in force, stable while its contents are. */
+const appConfigRecordAtom = selectAtom(
+  atom(
+    (get) =>
+      get(confirmedDocumentAtom)?.revision.app_config ?? get(pageAppConfigAtom),
+  ),
+  (record) => record,
+  dequal,
+);
+
+/** The notebook's app config, as the host document carries it. */
+export const appConfigAtom = atom((get) =>
+  parseAppConfig(get(appConfigRecordAtom)),
+);
+
+export function useAppConfig(): AppConfig {
+  return useAtomValue(appConfigAtom);
 }
 
 export function getAppConfig() {

package/src/core/islands/bootstrap.ts

@@ -221,7 +221,6 @@ function handleNotification(
           setLastRun: actions.setLastRun,
           resetCellRuntimes: actions.resetCellRuntimes,
           setLayoutData: Functions.NOOP,
-          setAppConfig: Functions.NOOP,
           setCapabilities: Functions.NOOP,
           setKernelState: Functions.NOOP,
           onError: Logger.error,

package/src/core/kernel/handlers.ts

@@ -1,11 +1,9 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 import type { LayoutType } from "@/components/editor/renderers/types";
-import { Logger } from "@/utils/Logger";
 import { Objects } from "@/utils/objects";
 import type { UIElementId } from "../cells/ids";
 import type { ReducerCellActions } from "../cells/cells";
 import type { CellData } from "../cells/types";
-import { type AppConfig, AppConfigSchema } from "../config/config-schema";
 import { UI_ELEMENT_REGISTRY } from "../dom/uiregistry";
 import { deserializeLayoutState } from "../layout/layout";
 import type { LayoutData, LayoutState } from "../layout/state";
@@ -71,7 +69,6 @@ export function handleKernelReady(
     }) => void;
     setCapabilities: (capabilities: Capabilities) => void;
     setKernelState: (state: KernelState) => void;
-    setAppConfig: (config: AppConfig) => void;
     onError: (error: Error) => void;
   },
 ): LayoutState {
@@ -81,13 +78,11 @@ export function handleKernelReady(
     setLastRun,
     resetCellRuntimes,
     setLayoutData,
-    setAppConfig,
     setCapabilities,
     setKernelState,
     onError,
   } = opts;
-  const { resumed, ui_values, app_config, capabilities, auto_instantiated } =
-    data;
+  const { resumed, ui_values, capabilities, auto_instantiated } = data;
 
   resetCellRuntimes();
   setLastRun({
@@ -96,13 +91,6 @@ export function handleKernelReady(
   });
   const layoutState = buildLayoutState(data, cells, setLayoutData);
 
-  // Set app config and capabilities
-  const parsedAppConfig = AppConfigSchema.safeParse(app_config);
-  if (parsedAppConfig.success) {
-    setAppConfig(parsedAppConfig.data);
-  } else {
-    Logger.error("Failed to parse app config", parsedAppConfig.error);
-  }
   setCapabilities(capabilities);
 
   // If the kernel was already instantiated server-side (e.g. run mode), we're done