@marimo-team/islands 0.25.3-dev28 → 0.25.3-dev281

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

@@ -7,6 +7,7 @@ import {
 } from "@/components/editor/cell/useDeleteCell";
 import { notebookAtom } from "@/core/cells/cells";
 import type { CellId } from "@/core/cells/ids";
+import { cellExecutionInputsAtom, cellExecutionView } from "@/core/executions";
 import type { JotaiStore } from "@/core/state/jotai";
 import { variablesAtom } from "@/core/variables/state";
 import type { VariableName } from "@/core/variables/types";
@@ -46,10 +47,11 @@ const { valueAtom: pendingDeleteStateAtom, useActions } = createReducerAndAtoms(
     ) => {
       const { cellIds, deleteCell, deleteManyCells, store } = action;
       const notebook = store.get(notebookAtom);
+      const executions = store.get(cellExecutionInputsAtom);
       const variables = store.get(variablesAtom);
 
       const emptyCells = new Set(
-        notebook.cellIds.inOrderIds.filter(
+        notebook.cellIds.filter(
           (id) => notebook.cellData[id].code.trim() === "",
         ),
       );
@@ -62,8 +64,6 @@ const { valueAtom: pendingDeleteStateAtom, useActions } = createReducerAndAtoms(
           continue;
         }
 
-        const runtimeInfo = notebook.cellRuntime[cellId];
-
         // Build defs map for this cell
         const defs = new Map<VariableName, readonly CellId[]>();
         for (const variable of Object.values(variables)) {
@@ -77,11 +77,9 @@ const { valueAtom: pendingDeleteStateAtom, useActions } = createReducerAndAtoms(
         }
 
         let executionDurationMs: number | undefined;
-        if (
-          runtimeInfo?.runElapsedTimeMs &&
-          runtimeInfo.runElapsedTimeMs > 2000
-        ) {
-          executionDurationMs = runtimeInfo.runElapsedTimeMs;
+        const { duration } = cellExecutionView(executions, cellId);
+        if (duration !== null && duration > 2000) {
+          executionDurationMs = duration;
         }
 
         if (defs.size === 0 && executionDurationMs === undefined) {
@@ -134,12 +132,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/scrollCellIntoView.ts

@@ -160,3 +160,9 @@ export function scrollCellIntoView(cellId: CellId): void {
     );
   }
 }
+
+export function scrollToCell(cellId: CellId): HTMLElement | null {
+  const cell = document.getElementById(HTMLCellId.create(cellId));
+  cell?.scrollIntoView({ behavior: "smooth", block: "center" });
+  return cell;
+}

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_fingerprint: 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,9 +1,7 @@
 /* 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 { CellConfig } from "../network/types";
 import type { CellId } from "./ids";
 import { DEFAULT_CELL_NAME } from "./names";
 import type { Outline } from "./outline";
@@ -15,11 +13,7 @@ export function createCell({
   id,
   name = DEFAULT_CELL_NAME,
   code = "",
-  lastCodeRun = null,
-  lastExecutionTime = null,
-  edited = false,
   config,
-  serializedEditorState = null,
 }: Partial<CellData> & { id: CellId }): CellData {
   return {
     id: id,
@@ -31,10 +25,6 @@ export function createCell({
     },
     name: name,
     code: code,
-    edited: edited,
-    lastCodeRun: lastCodeRun,
-    lastExecutionTime: lastExecutionTime,
-    serializedEditorState: serializedEditorState,
   };
 }
 
@@ -55,14 +45,6 @@ export function createCellRuntimeState(
     outline: null,
     output: null,
     consoleOutputs: [],
-    status: "idle" as RuntimeState,
-    staleInputs: false,
-    interrupted: false,
-    errored: false,
-    stopped: false,
-    runElapsedTimeMs: null,
-    runStartTimestamp: null,
-    lastRunStartTimestamp: null,
     debuggerActive: false,
     ...state,
   };
@@ -77,47 +59,26 @@ export interface CellData {
   name: string;
   /** current contents of the editor */
   code: string;
-  /** whether this cell has been modified since its last run */
-  edited: boolean;
-  /** snapshot of code that was last run */
-  lastCodeRun: string | null;
-  /** execution time on session start / resume */
-  lastExecutionTime: number | null;
   /** cell configuration */
   config: CellConfig;
-  /** serialized state of the underlying editor */
-  serializedEditorState: SerializedEditorState | null;
 }
 
+/**
+ * What the kernel's cell-ops still own. Status, timing, and how a cell last
+ * ended come from the host's executions (see `@/core/executions`).
+ *
+ * TODO(MO-8407): Delete.
+ */
 export interface CellRuntimeState {
-  /** a message encoding the cell's output */
+  /** a message encoding the cell's output. TODO(MO-8404) */
   output: OutputMessage | null;
-  /** TOC outline */
+  /** TOC outline. TODO(MO-8404) */
   outline: Outline | null;
-  /** messages encoding the cell's console outputs. */
-  consoleOutputs: WithResponse<OutputMessage>[];
-  /** current status of the cell */
-  status: RuntimeState;
-  /** whether the cell has stale inputs*/
-  staleInputs: boolean;
-  /** whether this cell has been interrupted since its last run */
-  interrupted: boolean;
-  /** whether this cell was stopped with mo.stop */
-  stopped: boolean;
-  /**
-   * whether marimo encountered an error when trying to register or run
-   * this cell (such as a multiple definition error)
-   */
-  errored: boolean;
-  /** run start time, as seconds since epoch */
-  runStartTimestamp: Seconds | null;
-  /** run elapsed time, in milliseconds */
-  runElapsedTimeMs: Milliseconds | null;
-  /** last run timestamp, as seconds since epoch */
-  lastRunStartTimestamp: Seconds | null;
+  /** messages encoding the cell's console outputs. TODO(MO-8405) */
+  consoleOutputs: ConsoleOutputMessage[];
   /** debugger active */
   debuggerActive: boolean;
-  /** serialization message */
+  /** serialization message. TODO(MO-8414) */
   serialization?: string | null;
 }
 
@@ -130,3 +91,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

@@ -1,31 +1,30 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
 import type { EditorView } from "@codemirror/view";
+import {
+  type CellExecutionInputs,
+  type CellExecutionView,
+  type CellFreshness,
+  type CellFreshnessLookup,
+  cellExecutionView,
+} from "@/core/executions";
+import type { Executions } from "@/core/notebook/replica";
 import { Objects } from "@/utils/objects";
 import type { MarimoError, OutputMessage } from "../kernel/messages";
 import { isErrorMime } from "../mime";
-import type { RuntimeState } from "../network/types";
 import type { NotebookState } from "./cells";
 import type { CellId } from "./ids";
 
-export function notebookIsRunning(state: NotebookState) {
-  return Object.values(state.cellRuntime).some(
-    (cell) => cell.status === "running",
-  );
-}
-
-export function notebookQueueOrRunningCount(state: NotebookState) {
-  return Object.values(state.cellRuntime).filter(
-    (cell) => cell.status === "running" || cell.status === "queued",
-  ).length;
-}
-
-export function notebookNeedsRun(state: NotebookState) {
-  return staleCellIds(state).length > 0;
+export function notebookNeedsRun(
+  state: NotebookState,
+  executions: CellExecutionInputs,
+  freshness: CellFreshnessLookup,
+) {
+  return staleCellIds(state, executions, freshness).length > 0;
 }
 
 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 +41,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 +53,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,19 +78,21 @@ 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(
+  executions: CellExecutionInputs,
+  freshness: CellFreshnessLookup,
+  descendants: readonly CellId[],
+) {
+  const views = descendants.map((id) => cellExecutionView(executions, id));
   const stale = descendants.some(
-    (id) => state.cellRuntime[id]?.staleInputs || state.cellData[id]?.edited,
+    (id) => freshness(id).sourceChanged || freshness(id).inputsChanged,
   );
-  const errored = descendants.some((id) => state.cellRuntime[id]?.errored);
-  const runningOrQueued = descendants.some(
-    (id) =>
-      state.cellRuntime[id]?.status === "running" ||
-      state.cellRuntime[id]?.status === "queued",
+  const errored = views.some((view) => view.outcome === "error");
+  const runningOrQueued = views.some(
+    (view) => view.status === "running" || view.status === "queued",
   );
 
   return {
@@ -104,77 +105,74 @@ export function getDescendantsStatus(state: NotebookState, cellId: CellId) {
 /**
  * Cells that are stale and can be run.
  */
-export function staleCellIds(state: NotebookState) {
-  const { cellIds, cellData, cellRuntime } = state;
-  return cellIds.inOrderIds.filter(
-    (cellId) =>
-      isUninstantiated({
-        // runElapstedTimeMs is what we've seen in this session
-        executionTime:
-          cellRuntime[cellId].runElapsedTimeMs ??
-          // lastExecutionTime is what was seen on session start/resume
-          cellData[cellId].lastExecutionTime,
-        status: cellRuntime[cellId].status,
-        errored: cellRuntime[cellId].errored,
-        interrupted: cellRuntime[cellId].interrupted,
-        stopped: cellRuntime[cellId].stopped,
-      }) ||
-      cellData[cellId].edited ||
-      cellRuntime[cellId].interrupted ||
-      (cellRuntime[cellId].staleInputs &&
-        // if a cell is disabled, it can't be run ...
-        !(
-          cellRuntime[cellId].status === "disabled-transitively" ||
-          cellData[cellId].config.disabled
-        )),
-  );
+export function staleCellIds(
+  state: NotebookState,
+  executions: CellExecutionInputs,
+  freshness: CellFreshnessLookup,
+) {
+  const { cellIds, cellData } = state;
+  return cellIds.filter((cellId) => {
+    const execution = cellExecutionView(executions, cellId);
+    if (execution.status !== "idle") {
+      // A run in progress covers the source it was asked for. Only an edit
+      // since then, visible once the host has planned the run, needs another.
+      return (
+        inFlight(executions.executions, cellId) &&
+        freshness(cellId).sourceChanged
+      );
+    }
+    return (
+      isUninstantiated(execution) ||
+      cellNeedsRun({
+        freshness: freshness(cellId),
+        interrupted: execution.outcome === "interrupted",
+        disabled: cellData[cellId].config.disabled,
+        blocked: execution.blocked,
+      })
+    );
+  });
+}
+
+/** Whether the host holds a planned or started execution of the cell that has not completed. */
+function inFlight(executions: Executions, cellId: CellId): boolean {
+  const latest = executions.latest.get(cellId);
+  const record =
+    latest === undefined
+      ? undefined
+      : executions.executions.get(latest)?.record;
+  return record !== undefined && record.status !== "completed";
 }
 
+/** Whether a cell has never run: no result to show and nothing in flight. */
 export function isUninstantiated({
-  executionTime,
   status,
-  errored,
-  interrupted,
-  stopped,
-}: {
-  executionTime: number | null;
-  status: RuntimeState;
-  errored: boolean;
-  interrupted: boolean;
-  stopped: boolean;
-}) {
-  return (
-    // hasn't run ...
-    executionTime === null &&
-    // isn't currently queued/running &&
-    status !== "queued" &&
-    status !== "running" &&
-    // and isn't in an error state.
-    !(errored || interrupted || stopped)
-  );
+  outcome,
+}: Pick<CellExecutionView, "status" | "outcome">) {
+  return outcome === null && status !== "queued" && status !== "running";
 }
 
 /**
- * Whether a cell needs to be run given its edited / interrupted / stale
- * inputs, while accounting for ancestor-disabled cells (which should not be
- * flagged as needing a run until re-enabled).
+ * Whether a cell needs to be run: its source changed, its last run was
+ * interrupted, or an input changed and the cell can run. A disabled cell,
+ * or one blocked by a disabled ancestor, is not flagged for changed inputs
+ * until it can run again.
  */
 export function cellNeedsRun({
-  edited,
+  freshness,
   interrupted,
-  staleInputs,
   disabled,
-  status,
+  blocked,
 }: {
-  edited: boolean;
+  freshness: CellFreshness;
   interrupted: boolean;
-  staleInputs: boolean;
   disabled: boolean | undefined;
-  status: RuntimeState;
+  blocked: boolean;
 }): boolean {
-  const disabledOrAncestorDisabled =
-    disabled || status === "disabled-transitively";
-  return edited || interrupted || (staleInputs && !disabledOrAncestorDisabled);
+  return (
+    freshness.sourceChanged ||
+    interrupted ||
+    (freshness.inputsChanged && !(disabled || blocked))
+  );
 }
 
 export function cellStatusClasses({
@@ -182,20 +180,20 @@ export function cellStatusClasses({
   errored,
   stopped,
   disabled,
-  status,
+  blocked,
 }: {
   needsRun: boolean;
   errored: boolean;
   stopped: boolean;
   disabled: boolean | undefined;
-  status: RuntimeState;
+  blocked: boolean;
 }) {
   return {
     "needs-run": needsRun,
     "has-error": errored,
     stopped,
     disabled: disabled ?? false,
-    stale: status === "disabled-transitively",
+    stale: blocked,
   };
 }