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

package/src/core/cells/cell.ts

@@ -1,13 +1,30 @@
 /* Copyright 2026 Marimo. All rights reserved. */
-import { logNever } from "@/utils/assertNever";
-import { invariant } from "@/utils/invariant";
-import { type Seconds, Time } from "@/utils/time";
+import type {
+  CellExecutionView,
+  CellFreshness,
+  CellRunStatus,
+} from "@/core/executions";
 import { extractAllTracebackInfo, type TracebackInfo } from "@/utils/traceback";
 import { parseOutline } from "../dom/outline";
 import type { CellMessage, OutputMessage } from "../kernel/messages";
-import type { RuntimeState } from "../network/types";
 import { collapseConsoleOutputs } from "./collapseConsoleOutputs";
-import type { CellRuntimeState } from "./types";
+import type { CellRuntimeState, ConsoleOutputMessage } from "./types";
+
+// Ids increase with position, so the last output holds the maximum.
+function nextConsoleOutputId(outputs: ConsoleOutputMessage[]): number {
+  return (outputs.at(-1)?.id ?? 0) + 1;
+}
+
+function errorTypes(output: OutputMessage | null | undefined): string[] {
+  if (
+    output == null ||
+    output.mimetype !== "application/vnd.marimo+error" ||
+    !Array.isArray(output.data)
+  ) {
+    return [];
+  }
+  return output.data.map((error) => error.type);
+}
 
 export function transitionCell(
   cell: CellRuntimeState,
@@ -15,105 +32,26 @@ export function transitionCell(
 ): CellRuntimeState {
   const nextCell = { ...cell };
 
-  // Handle status transition and update output; message.status !== null
-  // implies a status transition
-  switch (message.status) {
-    case "queued":
-      nextCell.interrupted = false;
-      nextCell.errored = false;
-      nextCell.runElapsedTimeMs = null;
-      nextCell.debuggerActive = false;
-      // We intentionally don't update lastCodeRun, since the kernel queues
-      // whatever code was last registered with it, which might not match
-      // the cell's current code if the user modified it.
-      break;
-    case "running":
-      // Clear interrupted here in case we start as "running"
-      // This can happen on a resumed session
-      nextCell.interrupted = false;
-      // If was previously stopped, clear the outputs
-      if (cell.stopped) {
-        nextCell.output = null;
-      }
-      // If it transitioned from queued to running, remove previous console outputs
-      if (nextCell.status === "queued") {
-        nextCell.consoleOutputs = [];
-      }
-      nextCell.stopped = false;
-      nextCell.runStartTimestamp = message.timestamp as Seconds;
-      // Store the last run timestamp, since this gets cleared once idle
-      nextCell.lastRunStartTimestamp = message.timestamp as Seconds;
-      break;
-    case "idle":
-      if (cell.runStartTimestamp) {
-        nextCell.runElapsedTimeMs = Time.fromSeconds(
-          ((message.timestamp ?? 0) - cell.runStartTimestamp) as Seconds,
-        ).toMilliseconds();
-        nextCell.runStartTimestamp = null;
-        nextCell.staleInputs = false;
-      }
-      // If last run start timestamp is not set, set it to the current timestamp
-      // This happens on a resumed session
-      if (!cell.lastRunStartTimestamp && message.timestamp) {
-        nextCell.lastRunStartTimestamp = message.timestamp as Seconds;
-      }
-      nextCell.debuggerActive = false;
-      break;
-    case null:
-      break;
-    case "disabled-transitively":
-      // Everything should already be up to date from prepareCellForExecution
-      break;
-    case undefined:
-      break;
-    default:
-      logNever(message.status);
+  if (message.status === "queued") {
+    nextCell.debuggerActive = false;
+  }
+  // A skipped cell's output is the notice that an ancestor stopped it, which
+  // has nothing to do with the run that is starting.
+  if (
+    message.status === "running" &&
+    errorTypes(cell.output).some((type) => type.includes("ancestor"))
+  ) {
+    nextCell.output = null;
   }
 
   nextCell.output = message.output ?? nextCell.output;
-  nextCell.staleInputs = message.stale_inputs ?? nextCell.staleInputs;
-  nextCell.status = message.status ?? nextCell.status;
   // Tri-state partial update: an omitted field (undefined) leaves the hint
   // unchanged; null explicitly clears it; a string sets it.
   if (message.serialization !== undefined) {
     nextCell.serialization = message.serialization;
   }
 
-  let didInterruptFromThisMessage = false;
-
-  // Handle errors: marimo includes an error output when a cell is interrupted
-  // or errored
-  if (
-    message.output != null &&
-    message.output.mimetype === "application/vnd.marimo+error"
-  ) {
-    // The frontend manually sets status to queued when a user runs a cell,
-    // to give immediate feedback, but the kernel doesn't know that.
-    //
-    // TODO(akshayka): Move all status management to the backend.
-    if (nextCell.status === "queued" || nextCell.status === "running") {
-      nextCell.status = "idle";
-    }
-
-    invariant(
-      Array.isArray(message.output.data),
-      "Expected error output data to be an array",
-    );
-    if (message.output.data.some((error) => error.type === "interruption")) {
-      // Interrupted helps distinguish that the cell is stale
-      nextCell.interrupted = true;
-      didInterruptFromThisMessage = true;
-    } else if (
-      message.output.data.some((error) => error.type.includes("ancestor"))
-    ) {
-      // The cell didn't run, but it was intentional, so don't count as
-      // errored.
-      nextCell.stopped = true;
-    } else {
-      // Communicate that the cell errored (e.g., an exception was raised)
-      nextCell.errored = true;
-    }
-  }
+  const interrupted = errorTypes(message.output).includes("interruption");
 
   // Coalesce console outputs, which are streamed during execution.
   let consoleOutputs = cell.consoleOutputs;
@@ -122,7 +60,7 @@ export function transitionCell(
   // stdin/pdb session, so resolve any dangling stdin prompt. This removes the
   // debugger box — e.g. after quitting pdb with `q`, which stops the cell
   // (idle) rather than interrupting it.
-  if (didInterruptFromThisMessage || message.status === "idle") {
+  if (interrupted || message.status === "idle") {
     nextCell.debuggerActive = false;
     consoleOutputs = consoleOutputs.map((output) => {
       if (output.channel === "stdin") {
@@ -133,6 +71,7 @@ export function transitionCell(
           mimetype: output.mimetype,
           data: output.data,
           timestamp: output.timestamp,
+          id: output.id,
           response: output.response ?? "",
         };
       }
@@ -146,8 +85,13 @@ export function transitionCell(
     // messageConsole is an output that needs to be appended to the
     // existing console outputs.
     consoleOutputs = Array.isArray(messageConsole)
-      ? collapseConsoleOutputs(messageConsole)
-      : collapseConsoleOutputs([...consoleOutputs, messageConsole]);
+      ? collapseConsoleOutputs(
+          messageConsole.map((output, i) => ({ ...output, id: i + 1 })),
+        )
+      : collapseConsoleOutputs([
+          ...consoleOutputs,
+          { ...messageConsole, id: nextConsoleOutputId(consoleOutputs) },
+        ]);
   }
   nextCell.consoleOutputs = consoleOutputs;
   // Derive outline from output
@@ -166,71 +110,59 @@ export function transitionCell(
   return nextCell;
 }
 
-// Should be called when a cell's code is registered with the kernel for
-// execution.
-export function prepareCellForExecution(
-  cell: CellRuntimeState,
-): CellRuntimeState {
-  const nextCell = { ...cell };
-
-  if (cell.status !== "disabled-transitively") {
-    // TODO(akshayka): Move this to the backend. It's in the FE right now
-    // to give the user immediate feedback.
-    nextCell.status = "queued";
-  }
-  nextCell.interrupted = false;
-  nextCell.errored = false;
-  nextCell.runElapsedTimeMs = null;
-  nextCell.debuggerActive = false;
-
-  return nextCell;
-}
-
 /**
  * A cell's output is loading if it is running or queued.
  */
-export function outputIsLoading(status: RuntimeState): boolean {
+export function outputIsLoading(status: CellRunStatus): boolean {
   return status === "running" || status === "queued";
 }
 
 /**
- * A cell's output is stale if it has been edited, is loading, or has errored.
+ * A cell's output is stale if it is loading, an input it read has changed,
+ * or, while `editing`, its source has changed. A read view keeps showing
+ * the last result of edited source.
  */
 export function outputIsStale(
-  cell: Pick<
-    CellRuntimeState,
-    "status" | "output" | "runStartTimestamp" | "interrupted" | "staleInputs"
-  >,
-  edited: boolean,
+  execution: Pick<CellExecutionView, "status" | "outcome" | "rendered">,
+  freshness: CellFreshness,
+  editing: boolean,
 ): boolean {
-  const { status, output, runStartTimestamp, interrupted, staleInputs } = cell;
+  const { status, outcome, rendered } = execution;
 
-  // If interrupted, the output is not stale
-  if (interrupted) {
-    return false;
+  // A run in progress owns the output area: loading until the running cell
+  // has shown output (e.g. mo.output.append()), whatever the last result was.
+  if (outputIsLoading(status)) {
+    return !(status === "running" && rendered);
   }
-
-  // If edited, the cell's output is stale
-  if (edited) {
+  if (editing && freshness.sourceChanged) {
     return true;
   }
+  // An interrupted run's partial output stands as the record of that run.
+  if (outcome === "interrupted") {
+    return false;
+  }
+  return freshness.inputsChanged;
+}
 
-  // The cell is loading
-  const loading = outputIsLoading(status);
-
-  // Output is received while the cell is running (e.g. mo.output.append())
-  const outputReceivedWhileRunning =
-    status === "running" &&
-    output !== null &&
-    runStartTimestamp !== null &&
-    (output.timestamp ?? 0) > runStartTimestamp;
-
-  // If loading and output has not been received while running
-  if (loading && !outputReceivedWhileRunning) {
+/**
+ * Console output is stale while a run is queued, since the run will clear
+ * it, and once a settled result is outdated. A run in progress owns it.
+ */
+export function consoleOutputIsStale(
+  execution: Pick<CellExecutionView, "status" | "outcome">,
+  freshness: CellFreshness,
+): boolean {
+  const { status, outcome } = execution;
+  if (outcome === "interrupted") {
+    return false;
+  }
+  if (status === "queued") {
     return true;
   }
-
-  return staleInputs;
+  if (status === "running") {
+    return false;
+  }
+  return freshness.sourceChanged || freshness.inputsChanged;
 }
 
 /**