@marimo-team/islands 0.25.3-dev29 → 0.25.3-dev291

package/src/core/executions/atoms.ts

@@ -0,0 +1,263 @@
+/* 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 { type CellFreshnessInputs, freshnessOf } from "./freshness";
+import type { CellOutputInputs } from "./output";
+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_CELLS: ReadonlyMap<Protocol.CellId, Protocol.Cell> = new Map();
+const NO_SUBMISSIONS: ReadonlyMap<
+  Protocol.CellId,
+  Protocol.ExecutionId | null
+> = new Map();
+const NO_BLOCKED: ReadonlySet<Protocol.CellId> = new Set();
+const NO_CLEARED: ReadonlyMap<Protocol.CellId, Protocol.ExecutionId> =
+  new Map();
+
+/**
+ * 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),
+  };
+});
+
+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)),
+);
+
+/** 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/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,48 @@
+/* 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,
+  cellFreshnessAtom,
+  cellOutputInputsAtom,
+  clearCellOutputs,
+  notebookIsRunningAtom,
+  notebookQueuedOrRunningCountAtom,
+  observeCellMessage,
+  runtimeStatusAtom,
+  submitCells,
+  waitForRuntimeRunning,
+  withdrawCells,
+} from "./atoms";
+export type { CellFreshness, CellFreshnessLookup } from "./freshness";
+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";