@marimo-team/islands 0.25.3-dev266 → 0.25.3-dev268

package/src/core/executions/__tests__/atoms.test.ts

@@ -0,0 +1,99 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { createStore } from "jotai";
+import { describe, expect, it } from "vitest";
+import { MockExecutions } from "@/__mocks__/executions";
+import { cellId } from "@/__tests__/branded";
+import type { CellMessage } from "@/core/kernel/messages";
+import {
+  cellExecutionInputsAtom,
+  notebookQueuedOrRunningCountAtom,
+  observeCellMessage,
+  submitCells,
+} from "../atoms";
+import { cellExecutionView } from "../select";
+
+const C1 = cellId("c1");
+
+function cellOp(status: CellMessage["status"]): CellMessage {
+  return {
+    cell_id: C1,
+    output: null,
+    console: null,
+    status,
+    stale_inputs: null,
+    timestamp: 1,
+  };
+}
+
+describe("observeCellMessage", () => {
+  it("withdraws a submission once the kernel reports the cell blocked", () => {
+    const store = createStore();
+    MockExecutions.seed(store, []);
+    submitCells(store, [C1]);
+    expect(
+      cellExecutionView(store.get(cellExecutionInputsAtom), C1).status,
+    ).toBe("queued");
+
+    observeCellMessage(store, cellOp("disabled-transitively"));
+
+    const view = cellExecutionView(store.get(cellExecutionInputsAtom), C1);
+    expect(view.status).toBe("idle");
+    expect(view.blocked).toBe(true);
+    expect(store.get(notebookQueuedOrRunningCountAtom)).toBe(0);
+  });
+
+  it("forgets submissions and blocked cells with the replica they were made for", () => {
+    const store = createStore();
+    MockExecutions.seed(store, []);
+    submitCells(store, [C1]);
+    observeCellMessage(store, cellOp("disabled-transitively"));
+
+    MockExecutions.seed(store, []);
+
+    const view = cellExecutionView(store.get(cellExecutionInputsAtom), C1);
+    expect(view.status).toBe("idle");
+    expect(view.blocked).toBe(false);
+    expect(store.get(notebookQueuedOrRunningCountAtom)).toBe(0);
+  });
+
+  it("keeps a submission while the cell is merely queued", () => {
+    const store = createStore();
+    MockExecutions.seed(store, []);
+    submitCells(store, [C1]);
+
+    observeCellMessage(store, cellOp("queued"));
+
+    expect(
+      cellExecutionView(store.get(cellExecutionInputsAtom), C1).status,
+    ).toBe("queued");
+  });
+
+  it("forgets acknowledged submissions and blocked cells when the replica follows a new notebook", () => {
+    const store = createStore();
+    const replica = MockExecutions.seed(store, []);
+    submitCells(store, [C1]);
+    observeCellMessage(store, {
+      ...cellOp("disabled-transitively"),
+      cell_id: cellId("c2"),
+    });
+
+    const completed = MockExecutions.inputs([MockExecutions.completed(C1)]);
+    store.set(replica.executionsAtom, completed.executions);
+    store.set(replica.resultsAtom, completed.results);
+    expect(
+      cellExecutionView(store.get(cellExecutionInputsAtom), C1).status,
+    ).toBe("idle");
+
+    const empty = MockExecutions.inputs([]);
+    store.set(replica.executionsAtom, empty.executions);
+    store.set(replica.resultsAtom, empty.results);
+    store.set(replica.notebookAtom, {
+      ...store.get(replica.notebookAtom),
+      id: "n2",
+    });
+
+    expect(store.get(cellExecutionInputsAtom)).toEqual(empty);
+    expect(store.get(notebookQueuedOrRunningCountAtom)).toBe(0);
+  });
+});

package/src/core/executions/__tests__/select.test.ts

@@ -0,0 +1,268 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type * as Protocol from "@marimo-team/client/protocol";
+import { describe, expect, it } from "vitest";
+import type { Execution, Executions, Results } from "@/core/notebook/replica";
+import {
+  anyRunning,
+  type CellExecutionInputs,
+  cellExecutionView,
+  onlyScratchRunning,
+  queuedOrRunningCount,
+  runningCellIds,
+} from "../select";
+
+const T0 = "2026-10-01T09:20:11Z";
+const T1 = "2026-10-01T09:20:12.500Z";
+const T2 = "2026-10-01T09:20:20Z";
+
+function record(
+  overrides: Partial<Protocol.Execution> & { id: string },
+): Protocol.Execution {
+  return {
+    run_id: "run-1",
+    runtime_id: "r1",
+    caused_by: null,
+    cell_id: "c1",
+    code: null,
+    code_fingerprint: "0f71456db2ea83f4",
+    depends_on: {},
+    status: "completed",
+    outcome: { kind: "value", display: null },
+    started_at: T0,
+    completed_at: T1,
+    ...overrides,
+  };
+}
+
+function execution(overrides: Partial<Protocol.Execution> & { id: string }) {
+  return { record: record(overrides), items: new Map(), variables: new Map() };
+}
+
+function inputs({
+  executions = [],
+  results = new Map(),
+  submissions = new Map(),
+  blocked = new Set(),
+}: {
+  executions?: Execution[];
+  results?: Results;
+  submissions?: ReadonlyMap<string, string | null>;
+  blocked?: ReadonlySet<string>;
+}): CellExecutionInputs {
+  const stream: Executions = {
+    runs: new Map(),
+    executions: new Map(executions.map((e) => [e.record.id, e])),
+    latest: new Map(
+      executions.flatMap((e) =>
+        e.record.cell_id === null ? [] : [[e.record.cell_id, e.record.id]],
+      ),
+    ),
+  };
+  return { executions: stream, results, submissions, blocked };
+}
+
+describe("cellExecutionView", () => {
+  it("is idle with no outcome before a cell runs", () => {
+    expect(cellExecutionView(inputs({}), "c1")).toEqual({
+      status: "idle",
+      blocked: false,
+      outcome: null,
+      startedAt: null,
+      duration: null,
+      rendered: false,
+    });
+  });
+
+  it("follows the execution on the stream while it is unfinished", () => {
+    const queued = inputs({
+      executions: [
+        execution({
+          id: "e1",
+          status: "queued",
+          outcome: null,
+          started_at: null,
+          completed_at: null,
+        }),
+      ],
+    });
+    expect(cellExecutionView(queued, "c1").status).toBe("queued");
+    const running = inputs({
+      executions: [
+        execution({
+          id: "e1",
+          status: "running",
+          outcome: null,
+          started_at: T2,
+          completed_at: null,
+        }),
+      ],
+      results: new Map([["c1", record({ id: "e0" })]]),
+    });
+    expect(cellExecutionView(running, "c1")).toEqual({
+      status: "running",
+      blocked: false,
+      outcome: null,
+      startedAt: Date.parse(T2),
+      duration: null,
+      rendered: false,
+    });
+  });
+
+  it("notes when a running execution has shown a value so far", () => {
+    const showing = inputs({
+      executions: [
+        execution({
+          id: "e1",
+          status: "running",
+          outcome: { kind: "value", display: null },
+          completed_at: null,
+        }),
+      ],
+    });
+    expect(cellExecutionView(showing, "c1").rendered).toBe(true);
+  });
+
+  it("reports how the last completed execution ended, with its timing", () => {
+    const ended = (outcome: Protocol.Outcome) =>
+      cellExecutionView(
+        inputs({
+          executions: [execution({ id: "e1", outcome })],
+          results: new Map([["c1", record({ id: "e1", outcome })]]),
+        }),
+        "c1",
+      );
+    const value = ended({ kind: "value", display: null });
+    expect(value).toEqual({
+      status: "idle",
+      blocked: false,
+      outcome: "value",
+      startedAt: Date.parse(T0),
+      duration: 1500,
+      rendered: false,
+    });
+    const error = (kind: string): Protocol.Outcome => ({
+      kind: "error",
+      error: {
+        kind,
+        message: "",
+        name: null,
+        traceback: null,
+        source: "marimo",
+        severity: "error",
+        range: null,
+        related: [],
+      },
+    });
+    expect(ended(error("exception")).outcome).toBe("error");
+    const skipped: Protocol.Outcome = {
+      kind: "skipped",
+      reason: "ancestor-stopped",
+      message: "",
+      related: [],
+    };
+    expect(ended(skipped).outcome).toBe("skipped");
+    expect(ended({ kind: "interrupted" }).outcome).toBe("interrupted");
+  });
+
+  it("reads as queued from a submission until the host shows a newer execution", () => {
+    const before = inputs({
+      executions: [execution({ id: "e1" })],
+      results: new Map([["c1", record({ id: "e1" })]]),
+      submissions: new Map([["c1", "e1"]]),
+    });
+    expect(cellExecutionView(before, "c1").status).toBe("queued");
+    expect(cellExecutionView(before, "c1").outcome).toBeNull();
+
+    // The stream let e1 go while the request was in flight; its result remains.
+    const forgotten = inputs({
+      results: new Map([["c1", record({ id: "e1" })]]),
+      submissions: new Map([["c1", "e1"]]),
+    });
+    expect(cellExecutionView(forgotten, "c1").status).toBe("queued");
+
+    const shown = inputs({
+      executions: [
+        execution({ id: "e2", status: "running", completed_at: null }),
+      ],
+      results: new Map([["c1", record({ id: "e1" })]]),
+      submissions: new Map([["c1", "e1"]]),
+    });
+    expect(cellExecutionView(shown, "c1").status).toBe("running");
+
+    const done = inputs({
+      executions: [execution({ id: "e2" })],
+      results: new Map([["c1", record({ id: "e2" })]]),
+      submissions: new Map([["c1", "e1"]]),
+    });
+    expect(cellExecutionView(done, "c1").status).toBe("idle");
+
+    const fresh = inputs({ submissions: new Map([["c1", null]]) });
+    expect(cellExecutionView(fresh, "c1").status).toBe("queued");
+  });
+
+  it("shows a blocked cell as disabled transitively, with its last outcome", () => {
+    const view = cellExecutionView(
+      inputs({
+        results: new Map([["c1", record({ id: "e1" })]]),
+        blocked: new Set(["c1"]),
+      }),
+      "c1",
+    );
+    expect(view.status).toBe("idle");
+    expect(view.blocked).toBe(true);
+    expect(view.outcome).toBe("value");
+  });
+});
+
+describe("notebook-level views", () => {
+  const stream = inputs({
+    executions: [
+      execution({ id: "e1", status: "running", completed_at: null }),
+      execution({
+        id: "e2",
+        cell_id: "c2",
+        status: "queued",
+        started_at: null,
+        completed_at: null,
+      }),
+      execution({ id: "e3", cell_id: "c3" }),
+      execution({
+        id: "s1",
+        cell_id: null,
+        status: "running",
+        completed_at: null,
+      }),
+    ],
+    results: new Map([["c5", record({ id: "e5", cell_id: "c5" })]]),
+    submissions: new Map([
+      ["c2", "e2"],
+      ["c4", null],
+      ["c5", "e5"],
+    ]),
+  });
+
+  it("counts unfinished executions and submissions the host has not shown", () => {
+    expect(anyRunning(stream.executions)).toBe(true);
+    expect(queuedOrRunningCount(stream)).toBe(5);
+    expect(runningCellIds(stream.executions)).toEqual(["c1"]);
+    expect(onlyScratchRunning(stream.executions)).toBe(false);
+  });
+
+  it("tells scratch work apart from cells", () => {
+    const scratch = inputs({
+      executions: [
+        execution({
+          id: "s1",
+          cell_id: null,
+          status: "running",
+          completed_at: null,
+        }),
+        execution({ id: "e3", cell_id: "c3" }),
+      ],
+    });
+    expect(anyRunning(scratch.executions)).toBe(true);
+    expect(onlyScratchRunning(scratch.executions)).toBe(true);
+    expect(queuedOrRunningCount(scratch)).toBe(1);
+  });
+});

package/src/core/executions/atoms.ts

@@ -0,0 +1,206 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/** The active notebook's executions and runtime as the editor reads them. */
+
+import type * as Protocol from "@marimo-team/client/protocol";
+import { atom, type createStore } from "jotai";
+import type { CellMessage } from "@/core/kernel/messages";
+import type {
+  Executions,
+  NotebookReplica,
+  Results,
+} from "@/core/notebook/replica";
+import { activeNotebookReplicaAtom } from "@/core/session/active-notebook";
+import { waitFor } from "@/core/state/jotai";
+import {
+  anyRunning,
+  type CellExecutionInputs,
+  latestExecutionId,
+  queuedOrRunningCount,
+} from "./select";
+
+type Store = ReturnType<typeof createStore>;
+
+const NO_EXECUTIONS: Executions = {
+  runs: new Map(),
+  executions: new Map(),
+  latest: new Map(),
+};
+const NO_RESULTS: Results = new Map();
+const NO_SUBMISSIONS: ReadonlyMap<
+  Protocol.CellId,
+  Protocol.ExecutionId | null
+> = new Map();
+const NO_BLOCKED: ReadonlySet<Protocol.CellId> = new Set();
+
+/**
+ * What the editor marks about cells of one replica's notebook.
+ *
+ * The marks are keyed by cell id, which another notebook, or the same one
+ * after a reconnect, reuses with different executions behind it. They
+ * therefore count only for the replica and host notebook they belong to.
+ */
+type Marks<T> = {
+  readonly notebook: {
+    readonly replica: NotebookReplica;
+    readonly id: Protocol.NotebookId;
+  };
+  readonly value: T;
+} | null;
+
+/**
+ * Cells a run was requested for, with the execution each had at the time.
+ *
+ * The host shows a queued execution once the kernel plans the run. Until
+ * then the cell reads as queued from this record. The host's newer
+ * execution supersedes it; a rejected request, a cell the kernel will not
+ * run, or the cell leaving the document withdraws it. Written only by
+ * `submitCells`, `withdrawCells`, and `observeCellMessage`.
+ */
+const submissionsAtom =
+  atom<Marks<ReadonlyMap<Protocol.CellId, Protocol.ExecutionId | null>>>(null);
+
+/**
+ * Cells the kernel reports as blocked by a disabled ancestor. Written only
+ * by `observeCellMessage`.
+ *
+ * TODO(MO-8463): Derive from the document and the analysis stream.
+ */
+const blockedCellsAtom = atom<Marks<ReadonlySet<Protocol.CellId>>>(null);
+
+function current<T>(
+  marks: Marks<T>,
+  replica: NotebookReplica | null,
+  notebookId: Protocol.NotebookId | null,
+  empty: T,
+): T {
+  return marks !== null &&
+    marks.notebook.replica === replica &&
+    marks.notebook.id === notebookId
+    ? marks.value
+    : empty;
+}
+
+function mark<T>(store: Store, value: T): Marks<T> {
+  const replica = store.get(activeNotebookReplicaAtom);
+  const notebook = replica === null ? null : store.get(replica.notebookAtom);
+  return replica === null || notebook === null
+    ? null
+    : { notebook: { replica, id: notebook.id }, value };
+}
+
+/** What every cell's view derives from. Pair with `cellExecutionView`. */
+export const cellExecutionInputsAtom = atom((get): CellExecutionInputs => {
+  const replica = get(activeNotebookReplicaAtom);
+  const notebookId =
+    replica === null ? null : (get(replica.notebookAtom)?.id ?? null);
+  return {
+    executions: replica === null ? NO_EXECUTIONS : get(replica.executionsAtom),
+    results: replica === null ? NO_RESULTS : get(replica.resultsAtom),
+    submissions: current(
+      get(submissionsAtom),
+      replica,
+      notebookId,
+      NO_SUBMISSIONS,
+    ),
+    blocked: current(get(blockedCellsAtom), replica, notebookId, NO_BLOCKED),
+  };
+});
+
+/** The runtime's status, null while the notebook has none or the stream is not ready. */
+export const runtimeStatusAtom = atom((get) => {
+  const replica = get(activeNotebookReplicaAtom);
+  return replica === null ? null : (get(replica.runtimeAtom)?.status ?? null);
+});
+
+export const notebookIsRunningAtom = atom((get) =>
+  anyRunning(get(cellExecutionInputsAtom).executions),
+);
+
+export const notebookQueuedOrRunningCountAtom = atom((get) =>
+  queuedOrRunningCount(get(cellExecutionInputsAtom)),
+);
+
+/** Resolve once the host reports the runtime running. */
+export async function waitForRuntimeRunning(): Promise<void> {
+  await waitFor(runtimeStatusAtom, (status) => status === "running");
+}
+
+/**
+ * Record a run request for `cellIds` so they read as queued at once.
+ *
+ * Cells blocked by a disabled ancestor stay blocked: the kernel will not
+ * queue them. A disabled cell is not queued either; the caller leaves it
+ * out, since its configuration lives in the notebook state.
+ */
+export function submitCells(
+  store: Store,
+  cellIds: readonly Protocol.CellId[],
+): void {
+  const inputs = store.get(cellExecutionInputsAtom);
+  const next = new Map(inputs.submissions);
+  for (const cellId of cellIds) {
+    if (!inputs.blocked.has(cellId)) {
+      next.set(cellId, latestExecutionId(inputs, cellId));
+    }
+  }
+  setSubmissions(store, next);
+}
+
+function setSubmissions(
+  store: Store,
+  value: ReadonlyMap<Protocol.CellId, Protocol.ExecutionId | null>,
+): void {
+  store.set(submissionsAtom, mark(store, value));
+}
+
+/** Forget a run request the host rejected. */
+export function withdrawCells(
+  store: Store,
+  cellIds: readonly Protocol.CellId[],
+): void {
+  const next = new Map(store.get(cellExecutionInputsAtom).submissions);
+  for (const cellId of cellIds) {
+    next.delete(cellId);
+  }
+  setSubmissions(store, next);
+}
+
+function setCellBlocked(
+  store: Store,
+  cellId: Protocol.CellId,
+  blocked: boolean,
+): void {
+  const known = store.get(cellExecutionInputsAtom).blocked;
+  if (known.has(cellId) === blocked) {
+    return;
+  }
+  const next = new Set(known);
+  if (blocked) {
+    next.add(cellId);
+  } else {
+    next.delete(cellId);
+  }
+  store.set(blockedCellsAtom, mark(store, next));
+}
+
+/**
+ * Keep the blocked set and the submissions in step with a cell-op.
+ *
+ * A status names whether the cell is blocked. A blocked cell and one whose
+ * output is an error will not run, so a submission that never became an
+ * execution is withdrawn, as it was when the editor set status itself.
+ *
+ * TODO(MO-8407): Delete with the cell-op case. The blocked read goes with
+ * MO-8463, the error read with MO-8346.
+ */
+export function observeCellMessage(store: Store, message: CellMessage): void {
+  const cellId = message.cell_id;
+  const blocked = message.status === "disabled-transitively";
+  if (message.status != null) {
+    setCellBlocked(store, cellId, blocked);
+  }
+  if (blocked || message.output?.mimetype === "application/vnd.marimo+error") {
+    withdrawCells(store, [cellId]);
+  }
+}

package/src/core/executions/hooks.ts

@@ -0,0 +1,31 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type * as Protocol from "@marimo-team/client/protocol";
+import { dequal } from "dequal";
+import { useAtomValue } from "jotai";
+import { selectAtom } from "jotai/utils";
+import { useMemo } from "react";
+import { cellExecutionInputsAtom } from "./atoms";
+import { type CellExecutionView, cellExecutionView } from "./select";
+
+/**
+ * A cell's status, timing, and how it last ended.
+ *
+ * Read from the host's executions, with the editor's own marks for a run
+ * it has requested and the kernel has not planned yet, and for a cell the
+ * kernel reports blocked by a disabled ancestor.
+ */
+export function useCellExecution(id: Protocol.CellId): CellExecutionView {
+  // One atom per mounted cell, kept for its subscription and compared by
+  // value so the cell renders only when its own view changes.
+  const cellAtom = useMemo(
+    () =>
+      selectAtom(
+        cellExecutionInputsAtom,
+        (inputs) => cellExecutionView(inputs, id),
+        dequal,
+      ),
+    [id],
+  );
+  return useAtomValue(cellAtom);
+}

package/src/core/executions/index.ts

@@ -0,0 +1,31 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/**
+ * Cell status and timing read from the host's executions.
+ *
+ * Every atom here is derived, so it can be read but not set. The state
+ * behind them changes only through `submitCells`, `withdrawCells`, and
+ * `observeCellMessage`.
+ */
+
+export {
+  cellExecutionInputsAtom,
+  notebookIsRunningAtom,
+  notebookQueuedOrRunningCountAtom,
+  observeCellMessage,
+  runtimeStatusAtom,
+  submitCells,
+  waitForRuntimeRunning,
+  withdrawCells,
+} from "./atoms";
+export { useCellExecution } from "./hooks";
+export {
+  type CellExecutionInputs,
+  type CellExecutionView,
+  type CellOutcome,
+  type CellRunStatus,
+  cellExecutionView,
+  onlyScratchRunning,
+  runningCellIds,
+  scratchStatus,
+} from "./select";