@marimo-team/islands 0.25.3-dev2 → 0.25.3-dev200

package/src/core/cells/layout.ts

@@ -0,0 +1,221 @@
+/* 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 { EditableDocument } from "@/core/notebook/document";
+import { findCollapseRange } from "../dom/outline";
+import { activeDocumentModelAtom } from "../session/active-notebook";
+import { cellOutlinesAtom } from "./cells";
+import { groupByColumn } from "./columns";
+import { CellId } from "./ids";
+import type { Outline } from "./outline";
+
+/** A column's identity on this page, as drag and drop and saved widths refer to it. */
+export type CellColumnId = string & { __brand: "CellColumnId" };
+
+/** The headers whose sections the user folded. Only this browser knows. */
+export const collapsedAtom = atom<ReadonlySet<CellId>>(new Set<CellId>());
+
+/**
+ * This browser's names for the document's columns, by position. The
+ * document knows columns only by position, so `followColumnsAtom` names
+ * a column as it appears and forgets one as it goes, and the column
+ * operations carry the names along as they rearrange.
+ */
+export const columnIdsAtom = atom<readonly CellColumnId[]>([]);
+
+/**
+ * Trailing columns a rearrangement here emptied. The document cannot hold
+ * an empty column at its end, so the page keeps them, as drop targets for
+ * the cell being dragged, until a drop compacts them.
+ */
+export const emptyColumnIdsAtom = atom<readonly CellColumnId[]>([]);
+
+export function newColumnId(): CellColumnId {
+  return `column-${CellId.create()}` as CellColumnId;
+}
+
+export function isColumnId(id: unknown): id is CellColumnId {
+  return typeof id === "string" && id.startsWith("column-");
+}
+
+/**
+ * Name the document's columns as the document changes. A column that
+ * appears takes over an empty column the page keeps, or gets a fresh id;
+ * one that goes is forgotten.
+ */
+export const followColumnsAtom = atom(
+  null,
+  (get, set, document: EditableDocument): void => {
+    const count = groupByColumn(document).length;
+    const ids = get(columnIdsAtom);
+    if (ids.length === count) {
+      return;
+    }
+    const empty = get(emptyColumnIdsAtom);
+    const named = [...ids, ...empty].slice(0, count);
+    while (named.length < count) {
+      named.push(newColumnId());
+    }
+    set(columnIdsAtom, named);
+    set(emptyColumnIdsAtom, empty.slice(Math.max(0, count - ids.length)));
+  },
+);
+
+/** The document's columns, each with its id, then the empty ones the page keeps. */
+function columnsOf(
+  document: EditableDocument | null,
+  ids: readonly CellColumnId[],
+  empty: readonly CellColumnId[],
+): Array<{ id: CellColumnId; ids: CellId[] }> {
+  const groups = document === null ? [[]] : groupByColumn(document);
+  return [
+    ...groups.map((cells, index) => ({
+      // Before the first document names them, columns go by position.
+      id: ids[index] ?? (`column-${index}` as CellColumnId),
+      ids: cells,
+    })),
+    ...empty.map((id) => ({ id, ids: [] as 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: the document's order and columns,
+ * this browser's column ids and folds, and the kernel's outlines.
+ *
+ * TODO(MO-8028): Outlines come from executions later.
+ */
+export const layoutAtom = atom((get): Layout => {
+  const model = get(activeDocumentModelAtom);
+  const document = model === null ? null : get(model.documentAtom);
+  const outlines = get(cellOutlinesAtom);
+  return deriveLayout(
+    columnsOf(document, get(columnIdsAtom), get(emptyColumnIdsAtom)),
+    (id) => outlines[id] ?? null,
+    get(collapsedAtom),
+  );
+});
+
+export const useLayout = () => useAtomValue(layoutAtom);
+
+export const numColumnsAtom = atom((get) => get(layoutAtom).columns.length);
+
+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/outputs.ts

@@ -1,15 +1,15 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
 import { useAtomValue } from "jotai";
-import { selectAtom } from "jotai/utils";
-import { useEffect, useMemo, useState } from "react";
+import { useEffect, useState } from "react";
 import { useEvent } from "@/hooks/useEvent";
-import { Logger } from "@/utils/Logger";
+import {
+  useNotebookCellConfig,
+  useNotebookDocumentEdit,
+} from "../notebook/document";
 import type { OutputMessage } from "../kernel/messages";
 import { viewStateAtom } from "../mode";
-import { getRequestClient } from "../network/requests";
-import { cellDataAtom, useCellActions } from "./cells";
-import type { CellId } from "./ids";
+import { type CellId, SCRATCH_CELL_ID } from "./ids";
 
 // This does not need to be overcomplicated. We can just store the expanded
 // state in a global map instead of Jotai since state is not shared between cells.
@@ -27,20 +27,9 @@ const expandedConsoleOutputs: Record<CellId, boolean> = {};
  */
 export function useExpandedOutput(cellId: CellId) {
   const { mode } = useAtomValue(viewStateAtom);
-  const { updateCellConfig } = useCellActions();
-  // Select just the flag: every output would otherwise re-render on each
-  // keystroke in its cell.
-  const isConfigExpanded = useAtomValue(
-    useMemo(
-      () =>
-        selectAtom(
-          cellDataAtom(cellId),
-          (data) => data?.config.expand_output ?? false,
-          Object.is,
-        ),
-      [cellId],
-    ),
-  );
+  const edit = useNotebookDocumentEdit();
+  const isConfigExpanded =
+    useNotebookCellConfig(cellId)?.expand_output ?? false;
   const [isSessionExpanded, setIsSessionExpanded] = useState(
     () => expandedOutputs[cellId] ?? isConfigExpanded,
   );
@@ -55,16 +44,11 @@ export function useExpandedOutput(cellId: CellId) {
 
   const setIsExpanded = useEvent((expanded: boolean) => {
     setIsSessionExpanded(expanded);
-    if (!isEditable) {
+    // The scratchpad is not in the document.
+    if (!isEditable || cellId === SCRATCH_CELL_ID) {
       return;
     }
-    const config = { expand_output: expanded };
-    updateCellConfig({ cellId, config });
-    getRequestClient()
-      .saveCellConfig({ configs: { [cellId]: config } })
-      .catch((error) => {
-        Logger.error("Failed to save expand_output config", error);
-      });
+    edit((tx) => tx.updateConfig(cellId, { expand_output: expanded }));
   });
 
   return [isExpanded, setIsExpanded] as const;

package/src/core/cells/pending-delete-service.ts

@@ -49,7 +49,7 @@ const { valueAtom: pendingDeleteStateAtom, useActions } = createReducerAndAtoms(
       const variables = store.get(variablesAtom);
 
       const emptyCells = new Set(
-        notebook.cellIds.inOrderIds.filter(
+        notebook.cellIds.filter(
           (id) => notebook.cellData[id].code.trim() === "",
         ),
       );
@@ -134,12 +134,8 @@ export function usePendingDeleteService() {
       submit({ cellIds, deleteCell, deleteManyCells, store });
     },
     clear,
-    get idle() {
-      return entries.size === 0;
-    },
-    get shouldConfirmDelete() {
-      return entries.size > 1;
-    },
+    idle: entries.size === 0,
+    shouldConfirmDelete: entries.size > 1,
   };
 }
 

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;
@@ -56,7 +58,7 @@ function mergeSessionAndNotebookCells(
     return {
       cellIds,
       sessionCellData: new Map(
-        cellIds.map((id, idx) => [id, null] as [CellId, SessionCell | null]),
+        cellIds.map((id) => [id, null] as [CellId, SessionCell | null]),
       ),
       notebookCellData: new Map(
         cellIds.map(
@@ -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,
   };
 }
 
@@ -206,8 +206,20 @@ function createCellRuntimeFromSession(
         channel: "marimo-error",
         data: [
           {
-            type: "unknown",
+            type: "exception",
+            exception_type: primaryOutput.ename,
             msg: primaryOutput.evalue,
+            raising_cell: null,
+            traceback:
+              primaryOutput.traceback.length === 0
+                ? null
+                : primaryOutput.traceback
+                    .map((line, index, lines) =>
+                      index < lines.length - 1 && !line.endsWith("\n")
+                        ? `${line}\n`
+                        : line,
+                    )
+                    .join(""),
           },
         ],
         mimetype: "application/vnd.marimo+error",
@@ -223,6 +235,9 @@ function createCellRuntimeFromSession(
         timestamp: DEFAULT_TIMESTAMP,
       };
     }
+    if (runtimeState.output && primaryOutput.code !== undefined) {
+      runtimeState.output.code = primaryOutput.code;
+    }
   }
 
   const consoleOutputs = sessionCell.console || [];
@@ -237,7 +252,13 @@ function createCellRuntimeFromSession(
           channel: "media",
           data: consoleOutput.data,
           mimetype: consoleOutput.mimetype,
+          ...(consoleOutput.traceback_format === undefined
+            ? {}
+            : { traceback_format: consoleOutput.traceback_format }),
           timestamp: DEFAULT_TIMESTAMP,
+          ...(consoleOutput.code === undefined
+            ? {}
+            : { code: consoleOutput.code }),
         };
       }
       // Handle StreamOutput (type: "stream")
@@ -245,51 +266,80 @@ function createCellRuntimeFromSession(
         channel: consoleOutput.name === "stderr" ? "stderr" : "stdout",
         data: consoleOutput.text,
         mimetype: consoleOutput.mimetype ?? "text/plain",
+        ...(consoleOutput.traceback_format === undefined
+          ? {}
+          : { traceback_format: consoleOutput.traceback_format }),
         timestamp: DEFAULT_TIMESTAMP,
+        ...(consoleOutput.code === undefined
+          ? {}
+          : { code: consoleOutput.code }),
       };
     }),
   };
 }
 
-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,13 +1,24 @@
 /* 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";
 import { DEFAULT_CELL_NAME } from "./names";
 import type { Outline } from "./outline";
 
+/**
+ * Whether a cell's code has changed since it last ran. A cell that never ran
+ * is edited once it has code. Whitespace at the ends does not count.
+ *
+ * TODO(MO-8028): Temporary until staleness comes from the host's executions.
+ */
+export function isEdited(lastCodeRun: string | null, code: string): boolean {
+  return lastCodeRun === null
+    ? code.trim().length > 0
+    : lastCodeRun.trim() !== code.trim();
+}
+
 /**
  * Create a new cell with default state.
  */
@@ -19,7 +30,6 @@ export function createCell({
   lastExecutionTime = null,
   edited = false,
   config,
-  serializedEditorState = null,
 }: Partial<CellData> & { id: CellId }): CellData {
   return {
     id: id,
@@ -34,7 +44,6 @@ export function createCell({
     edited: edited,
     lastCodeRun: lastCodeRun,
     lastExecutionTime: lastExecutionTime,
-    serializedEditorState: serializedEditorState,
   };
 }
 
@@ -85,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 {
@@ -95,7 +102,7 @@ export interface CellRuntimeState {
   /** TOC outline */
   outline: Outline | null;
   /** messages encoding the cell's console outputs. */
-  consoleOutputs: WithResponse<OutputMessage>[];
+  consoleOutputs: ConsoleOutputMessage[];
   /** current status of the cell */
   status: RuntimeState;
   /** whether the cell has stale inputs*/
@@ -130,3 +137,12 @@ export type WithResponse<T> = T & {
    */
   response?: string;
 };
+
+/**
+ * A console output as held by the frontend. The id is assigned when the
+ * output arrives and never changes, so it can identify the output while
+ * neighboring outputs collapse, truncate, or receive a stdin response.
+ */
+export type ConsoleOutputMessage = WithResponse<OutputMessage> & {
+  id?: number;
+};

package/src/core/cells/utils.ts

@@ -25,7 +25,7 @@ export function notebookNeedsRun(state: NotebookState) {
 }
 
 export function notebookCells(state: NotebookState) {
-  return state.cellIds.inOrderIds.map((cellId) => state.cellData[cellId]);
+  return state.cellIds.map((cellId) => state.cellData[cellId]);
 }
 
 export function notebookCellEditorViews({ cellHandles }: NotebookState) {
@@ -42,7 +42,7 @@ export function notebookCellEditorViews({ cellHandles }: NotebookState) {
 export function disabledCellIds(state: NotebookState) {
   const { cellIds, cellData } = state;
   const disabledCells: CellId[] = [];
-  for (const cellId of cellIds.inOrderIds) {
+  for (const cellId of cellIds) {
     const cell = cellData[cellId];
     if (cell.config.disabled) {
       disabledCells.push(cellId);
@@ -54,7 +54,7 @@ export function disabledCellIds(state: NotebookState) {
 export function enabledCellIds(state: NotebookState) {
   const { cellIds, cellData } = state;
   const enabledCells: CellId[] = [];
-  for (const cellId of cellIds.inOrderIds) {
+  for (const cellId of cellIds) {
     const cell = cellData[cellId];
     if (!cell.config.disabled) {
       enabledCells.push(cellId);
@@ -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,
   );
@@ -106,7 +108,7 @@ export function getDescendantsStatus(state: NotebookState, cellId: CellId) {
  */
 export function staleCellIds(state: NotebookState) {
   const { cellIds, cellData, cellRuntime } = state;
-  return cellIds.inOrderIds.filter(
+  return cellIds.filter(
     (cellId) =>
       isUninstantiated({
         // runElapstedTimeMs is what we've seen in this session