@marimo-team/islands 0.25.3-dev31 → 0.25.3-dev311

package/src/core/executions/atoms.ts

@@ -0,0 +1,378 @@
+/* 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 {
+  ConnectionState,
+  type Executions,
+  type NotebookReplica,
+  type Results,
+} from "@/core/notebook/replica";
+import { activeNotebookReplicaAtom } from "@/core/session/active-notebook";
+import { type CellFreshnessInputs, freshnessOf } from "./freshness";
+import type { CellOutputInputs } from "./output";
+import {
+  anyRunning,
+  type CellExecutionInputs,
+  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_CELLS: ReadonlyMap<Protocol.CellId, Protocol.Cell> = new Map();
+const NO_REQUESTS: ReadonlySet<RunRequest> = new Set();
+const NO_REQUESTED: ReadonlySet<Protocol.CellId> = new Set();
+const NO_BLOCKED: ReadonlySet<Protocol.CellId> = new Set();
+const NO_CLEARED: ReadonlyMap<Protocol.CellId, Protocol.ExecutionId> =
+  new Map();
+
+/** The notebook a replica is showing, which the editor's marks belong to. */
+interface ShownNotebook {
+  readonly replica: NotebookReplica;
+  readonly id: Protocol.NotebookId;
+}
+
+/**
+ * What the editor marks about cells of one replica's notebook.
+ *
+ * The marks refer to cells by 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: ShownNotebook;
+  readonly value: T;
+} | null;
+
+/**
+ * A run this browser has asked the host for.
+ *
+ * The host answers some time after the request is made, and by then the
+ * notebook may have been replaced or the same cells asked for again. So
+ * the functions that handle the answer are given the request back, and
+ * they act only on it, in the notebook it was made in.
+ */
+export interface RunRequest {
+  readonly notebook: ShownNotebook;
+  readonly cells: readonly Protocol.CellId[];
+}
+
+/**
+ * Requests whose run has not appeared on the stream yet.
+ *
+ * They let a requested cell read as queued right away. Once the host
+ * accepts the run, the stream shows it with the same cells named on it,
+ * and the request is no longer needed. A request the host refuses, or
+ * that the browser gives up on, is withdrawn instead.
+ */
+const requestsAtom = atom<Marks<ReadonlySet<RunRequest>>>(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 shownNotebook(store: Store): ShownNotebook | null {
+  const replica = store.get(activeNotebookReplicaAtom);
+  const notebook = replica === null ? null : store.get(replica.notebookAtom);
+  return replica === null || notebook === null
+    ? null
+    : { replica, id: notebook.id };
+}
+
+function mark<T>(store: Store, value: T): Marks<T> {
+  const notebook = shownNotebook(store);
+  return notebook === null ? null : { notebook, value };
+}
+
+/**
+ * Whether `request` still belongs to the notebook being shown.
+ *
+ * Between a reset and the next snapshot the replica has no notebook for a
+ * moment. That says nothing about where the request belongs, so it does
+ * not count against it. Another replica, or another notebook on the same
+ * replica, does.
+ */
+export function isCurrent(store: Store, request: RunRequest): boolean {
+  const replica = store.get(activeNotebookReplicaAtom);
+  if (replica !== request.notebook.replica) {
+    return false;
+  }
+  const notebook = store.get(replica.notebookAtom);
+  return notebook === null || notebook.id === request.notebook.id;
+}
+
+/** Cells named by pending requests made in the notebook now shown. */
+const requestedCellsAtom = atom((get) => {
+  const replica = get(activeNotebookReplicaAtom);
+  const notebookId =
+    replica === null ? null : (get(replica.notebookAtom)?.id ?? null);
+  const requests = current(get(requestsAtom), replica, notebookId, NO_REQUESTS);
+  return requests.size === 0
+    ? NO_REQUESTED
+    : new Set([...requests].flatMap((request) => request.cells));
+});
+
+/** 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);
+  const document = replica === null ? null : get(replica.documentAtom);
+  return {
+    executions: replica === null ? NO_EXECUTIONS : get(replica.executionsAtom),
+    results: replica === null ? NO_RESULTS : get(replica.resultsAtom),
+    cells: document?.cells ?? NO_CELLS,
+    requested: get(requestedCellsAtom),
+    blocked: current(get(blockedCellsAtom), replica, notebookId, NO_BLOCKED),
+  };
+});
+
+const cellFreshnessInputsAtom = atom((get): CellFreshnessInputs => {
+  const replica = get(activeNotebookReplicaAtom);
+  const document = replica === null ? null : get(replica.documentAtom);
+  // Results can arrive before the confirmed document on a snapshot. Until
+  // the document is ready there is nothing to compare them against.
+  if (replica === null || document === null) {
+    return { cells: NO_CELLS, executions: NO_EXECUTIONS, results: NO_RESULTS };
+  }
+  return {
+    cells: document.cells,
+    executions: get(replica.executionsAtom),
+    results: get(replica.resultsAtom),
+  };
+});
+
+/** Freshness by cell id, indexed once per change to its inputs. */
+export const cellFreshnessAtom = atom((get) =>
+  freshnessOf(get(cellFreshnessInputsAtom)),
+);
+
+/** Results this browser cleared, by execution id, until a newer one lands. */
+const clearedOutputsAtom =
+  atom<Marks<ReadonlyMap<Protocol.CellId, Protocol.ExecutionId>>>(null);
+
+/** What every cell's output derives from. Pair with `cellOutputView`. */
+export const cellOutputInputsAtom = atom((get): CellOutputInputs => {
+  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),
+    cleared: current(get(clearedOutputsAtom), replica, notebookId, NO_CLEARED),
+  };
+});
+
+/** Hide what `cellIds` show now, until each has a newer result. */
+export function clearCellOutputs(
+  store: Store,
+  cellIds: readonly Protocol.CellId[],
+): void {
+  const inputs = store.get(cellOutputInputsAtom);
+  const next = new Map(inputs.cleared);
+  for (const cellId of cellIds) {
+    const result = inputs.results.get(cellId);
+    if (result !== null && result !== undefined) {
+      next.set(cellId, result.id);
+    }
+  }
+  store.set(clearedOutputsAtom, mark(store, next));
+}
+
+/** 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)),
+);
+
+type RuntimeReadiness = "running" | "waiting" | { refused: string };
+
+/**
+ * Whether a run can go to the host now, should wait, or has nothing to wait for.
+ *
+ * A runtime that is starting, or a stream that has not reported yet, will
+ * settle one way or the other. A failed or absent runtime, or a connection
+ * that has closed, will not, so a run waiting on it is refused instead.
+ */
+const runtimeReadinessAtom = atom((get): RuntimeReadiness => {
+  const replica = get(activeNotebookReplicaAtom);
+  if (replica === null) {
+    return { refused: "No notebook is connected" };
+  }
+  if (get(replica.connectionAtom).state === ConnectionState.CLOSED) {
+    return { refused: "The notebook is disconnected" };
+  }
+  // Until the stream's snapshot is complete there is no notebook to speak
+  // of, and nothing it reports about the runtime counts yet.
+  if (get(replica.notebookAtom) === null) {
+    return "waiting";
+  }
+  const runtime = get(replica.runtimeAtom);
+  if (runtime === null) {
+    return { refused: "The notebook has no runtime" };
+  }
+  switch (runtime.status) {
+    case "running":
+      return "running";
+    case "failed":
+      return { refused: runtime.message ?? "The runtime failed" };
+    default:
+      return "waiting";
+  }
+});
+
+/** Resolve once the host reports the runtime running; reject once it cannot. */
+export function waitForRuntimeRunning(store: Store): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const unsubscribe = store.sub(runtimeReadinessAtom, check);
+    function check() {
+      const readiness = store.get(runtimeReadinessAtom);
+      if (readiness === "waiting") {
+        return;
+      }
+      unsubscribe();
+      if (readiness === "running") {
+        resolve();
+      } else {
+        reject(new Error(readiness.refused));
+      }
+    }
+    check();
+  });
+}
+
+/**
+ * Record that this browser is asking the host to run `cellIds`, so that
+ * they read as queued before the host has answered.
+ *
+ * A disabled cell, or one the kernel reports as blocked, may be among them
+ * so the kernel can set it aside, but the views do not show it as queued.
+ * Returns null while no notebook is shown, since there is nothing to
+ * record the request against.
+ */
+export function requestRun(
+  store: Store,
+  cellIds: readonly Protocol.CellId[],
+): RunRequest | null {
+  const notebook = shownNotebook(store);
+  if (notebook === null) {
+    return null;
+  }
+  const request: RunRequest = { notebook, cells: [...cellIds] };
+  const marks = store.get(requestsAtom);
+  const kept =
+    marks !== null &&
+    marks.notebook.replica === notebook.replica &&
+    marks.notebook.id === notebook.id
+      ? marks.value
+      : NO_REQUESTS;
+  store.set(requestsAtom, { notebook, value: new Set(kept).add(request) });
+  return request;
+}
+
+/** Forget a request the host refused or the browser gave up on. */
+export function withdrawRequest(store: Store, request: RunRequest): void {
+  const marks = store.get(requestsAtom);
+  if (marks === null || !marks.value.has(request)) {
+    return;
+  }
+  const value = new Set(marks.value);
+  value.delete(request);
+  store.set(requestsAtom, { notebook: marks.notebook, value });
+}
+
+/**
+ * Keep a request until the run the host accepted for it appears on the
+ * stream, which can happen after the response has arrived. From then on
+ * the run itself says which cells are queued. If the notebook is no
+ * longer shown by then, the request is simply dropped.
+ */
+export function acceptRun(
+  store: Store,
+  request: RunRequest,
+  run: Protocol.Run,
+): void {
+  const { replica } = request.notebook;
+  const unsubscribe = store.sub(replica.executionsAtom, check);
+  function check() {
+    if (
+      isCurrent(store, request) &&
+      !store.get(replica.executionsAtom).runs.has(run.id)
+    ) {
+      return;
+    }
+    unsubscribe();
+    withdrawRequest(store, request);
+  }
+  check();
+}
+
+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));
+}
+
+/**
+ * Learn from a cell-op whether the kernel considers the cell blocked by a
+ * disabled ancestor. A blocked cell will not run, so a run that names it
+ * does not show it as queued.
+ *
+ * TODO(MO-8407): Delete with the cell-op case. The blocked read goes with
+ * MO-8463.
+ */
+export function observeCellMessage(store: Store, message: CellMessage): void {
+  if (message.status != null) {
+    setCellBlocked(
+      store,
+      message.cell_id,
+      message.status === "disabled-transitively",
+    );
+  }
+}

package/src/core/executions/freshness.ts

@@ -0,0 +1,171 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/**
+ * Whether each cell's result still reflects the document and the values
+ * it read, by the host protocol's rules.
+ *
+ * A completed execution is current when its code fingerprint equals the
+ * cell's, every variable it depends on still holds the recorded revision,
+ * every name it depends on that was unbound is still unbound, and the
+ * executions that bound those variables are current. See the freshness
+ * section of `protocols/host/spec.md`.
+ *
+ * The protocol also ranks why a result is outdated. The editor asks two
+ * questions of its own, so that is what this reports; the ranked reason
+ * can come back with a reader. Two editor concerns are folded in: a name
+ * bound only by an earlier runtime is unbound in this one, and a queued or
+ * running execution for the cell's current source already covers it.
+ */
+
+import type * as Protocol from "@marimo-team/client/protocol";
+import type { Executions, Results } from "@/core/notebook/replica";
+
+export interface CellFreshness {
+  /** This cell's source differs from its pending execution, or its last result. */
+  readonly sourceChanged: boolean;
+  /**
+   * A value the result read changed since, by a rerun or an update, here
+   * or upstream. An ancestor that was only edited does not count: its
+   * values are still the ones this result read.
+   */
+  readonly inputsChanged: boolean;
+}
+
+/** Current, and also a cell with no completed execution to compare. */
+const CURRENT: CellFreshness = { sourceChanged: false, inputsChanged: false };
+
+/** What freshness is derived from. */
+export interface CellFreshnessInputs {
+  /** The document's cells, for the fingerprint of each cell's source. */
+  readonly cells: ReadonlyMap<Protocol.CellId, Protocol.Cell>;
+  /** The stream's executions, for the variables currently bound. */
+  readonly executions: Executions;
+  /** Each cell's last completed record, the result being compared. */
+  readonly results: Results;
+}
+
+/** Freshness by cell id, as `freshnessOf` builds it. */
+export type CellFreshnessLookup = (id: Protocol.CellId) => CellFreshness;
+
+/** The variables bound in the namespace right now, by name. */
+function boundVariables(
+  executions: Executions,
+): ReadonlyMap<string, Protocol.Variable[]> {
+  const byName = new Map<string, Protocol.Variable[]>();
+  for (const execution of executions.executions.values()) {
+    for (const variable of execution.variables.values()) {
+      const bound = byName.get(variable.name);
+      if (bound === undefined) {
+        byName.set(variable.name, [variable]);
+      } else {
+        bound.push(variable);
+      }
+    }
+  }
+  return byName;
+}
+
+/**
+ * Compares results against the document and the namespace.
+ *
+ * Build one per set of inputs and ask it about each cell, since the
+ * bound variables are indexed once and a binding execution's freshness is
+ * computed once however many results depend on it.
+ */
+export function freshnessOf(inputs: CellFreshnessInputs): CellFreshnessLookup {
+  const bound = boundVariables(inputs.executions);
+  const memo = new Map<Protocol.ExecutionId, CellFreshness>();
+  const recordOf = (id: Protocol.ExecutionId) =>
+    inputs.executions.executions.get(id)?.record;
+
+  /** Whether a value the record read has changed, or one upstream has. */
+  function inputsChanged(
+    record: Protocol.Execution,
+    visiting: ReadonlySet<Protocol.ExecutionId>,
+  ): boolean {
+    const path = new Set(visiting).add(record.id);
+    for (const [name, revision] of Object.entries(record.depends_on)) {
+      const variables = bound.get(name) ?? [];
+      if (revision === null) {
+        // Older runtimes bind nothing here, but a later binding invalidates
+        // the result even if its runtime has since stopped.
+        if (
+          variables.some((v) => {
+            const binder = recordOf(v.execution_id);
+            if (binder === undefined) {
+              return false;
+            }
+            if (binder.runtime_id === record.runtime_id) {
+              return true;
+            }
+            const boundAt = binder.completed_at ?? binder.started_at;
+            return (
+              boundAt !== null &&
+              record.completed_at !== null &&
+              Date.parse(boundAt) > Date.parse(record.completed_at)
+            );
+          })
+        ) {
+          return true;
+        }
+        continue;
+      }
+      const variable = variables.find(
+        (candidate) => candidate.revision.execution === revision.execution,
+      );
+      if (
+        variable === undefined ||
+        variable.revision.update !== revision.update
+      ) {
+        return true;
+      }
+      const binder = recordOf(variable.execution_id);
+      if (binder === undefined) {
+        return true;
+      }
+      if (!path.has(binder.id) && ofRecord(binder, path).inputsChanged) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /** Compare against pending work before the result it will replace. */
+  function sourceChanged(
+    cell: Protocol.Cell,
+    result: Protocol.Execution,
+  ): boolean {
+    const latest = inputs.executions.latest.get(cell.id);
+    const pending = latest === undefined ? undefined : recordOf(latest);
+    const source =
+      pending !== undefined && pending.status !== "completed"
+        ? pending
+        : result;
+    return cell.code_fingerprint !== source.code_fingerprint;
+  }
+
+  function ofRecord(
+    record: Protocol.Execution,
+    visiting: ReadonlySet<Protocol.ExecutionId>,
+  ): CellFreshness {
+    const known = memo.get(record.id);
+    if (known !== undefined) {
+      return known;
+    }
+    const cell =
+      record.cell_id === null ? undefined : inputs.cells.get(record.cell_id);
+    const freshness: CellFreshness = {
+      sourceChanged: cell === undefined || sourceChanged(cell, record),
+      inputsChanged: inputsChanged(record, visiting),
+    };
+    memo.set(record.id, freshness);
+    return freshness;
+  }
+
+  return (id) => {
+    const result = inputs.results.get(id);
+    return result === null || result === undefined
+      ? CURRENT
+      : ofRecord(result, new Set());
+  };
+}

package/src/core/executions/hooks.ts

@@ -0,0 +1,86 @@
+/* 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 { parseOutline } from "@/core/dom/outline";
+import {
+  cellExecutionInputsAtom,
+  cellFreshnessAtom,
+  cellOutputInputsAtom,
+} from "./atoms";
+import type { CellFreshness } from "./freshness";
+import { type CellOutput, cellOutputView, scratchOutputView } from "./output";
+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);
+}
+
+/**
+ * Whether a cell's result is current, by the host protocol's rules.
+ *
+ * The comparison reads the confirmed document, so an edit counts once the
+ * host has it, not on the keystroke.
+ */
+export function useCellFreshness(id: Protocol.CellId): CellFreshness {
+  const cellAtom = useMemo(
+    () => selectAtom(cellFreshnessAtom, (freshness) => freshness(id), dequal),
+    [id],
+  );
+  return useAtomValue(cellAtom);
+}
+
+/** What the cell shows: its running value so far, else its result's outcome. */
+export function useCellOutput(id: Protocol.CellId): CellOutput | null {
+  const cellAtom = useMemo(
+    () =>
+      selectAtom(
+        cellOutputInputsAtom,
+        (inputs) => cellOutputView(inputs, id),
+        dequal,
+      ),
+    [id],
+  );
+  return useAtomValue(cellAtom);
+}
+
+/** The headings in the cell's output, for the table of contents. */
+export function useCellOutline(id: Protocol.CellId) {
+  const output = useCellOutput(id);
+  return useMemo(() => parseOutline(output), [output]);
+}
+
+/** What the scratchpad shows, from its latest scratch execution. */
+export function useScratchOutput(): CellOutput | null {
+  const scratchAtom = useMemo(
+    () =>
+      selectAtom(
+        cellOutputInputsAtom,
+        (inputs) => scratchOutputView(inputs.executions),
+        dequal,
+      ),
+    [],
+  );
+  return useAtomValue(scratchAtom);
+}

package/src/core/executions/index.ts

@@ -0,0 +1,49 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/**
+ * Cell status, timing, and output, as the editor reads them.
+ *
+ * The host's notebook stream is the source of truth. Its runs, executions,
+ * and results say what every cell is doing. The atoms here derive views
+ * from that stream, adding only what the host cannot know yet, such as a
+ * run this browser has asked for but not heard back about.
+ */
+
+export {
+  cellExecutionInputsAtom,
+  cellFreshnessAtom,
+  cellOutputInputsAtom,
+  clearCellOutputs,
+  notebookIsRunningAtom,
+  notebookQueuedOrRunningCountAtom,
+  observeCellMessage,
+  runtimeStatusAtom,
+  waitForRuntimeRunning,
+} from "./atoms";
+export type { CellFreshness, CellFreshnessLookup } from "./freshness";
+export { replyInput } from "./input";
+export { runCells, syncEdits, waitForRuntime } from "./run";
+export {
+  useCellExecution,
+  useCellFreshness,
+  useCellOutline,
+  useCellOutput,
+  useScratchOutput,
+} from "./hooks";
+export {
+  type CellError,
+  type CellOutput,
+  cellOutputView,
+  type HostDiagnostic,
+  scratchOutputView,
+} from "./output";
+export {
+  type CellExecutionInputs,
+  type CellExecutionView,
+  type CellOutcome,
+  type CellRunStatus,
+  cellExecutionView,
+  onlyScratchRunning,
+  runningCellIds,
+  scratchStatus,
+} from "./select";