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

package/src/core/executions/input.ts

@@ -0,0 +1,55 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/** Answer a prompt the runtime is waiting on. */
+
+import type * as Protocol from "@marimo-team/client/protocol";
+import type { createStore } from "jotai";
+import { toast } from "@/components/ui/use-toast";
+import { activeNotebookReplicaAtom } from "@/core/session/active-notebook";
+import { prettyError } from "@/utils/errors";
+import { Logger } from "@/utils/Logger";
+
+type Store = ReturnType<typeof createStore>;
+
+/**
+ * Send `value` to the host as the answer to the prompt `inputId`.
+ *
+ * The reply names its prompt, so the host marks that prompt answered for
+ * every client and refuses a reply to one that has already been answered
+ * or cancelled. A refusal is reported, since the user typed the answer and
+ * would otherwise wait on a prompt that is not going to take it.
+ */
+export async function replyInput(
+  store: Store,
+  inputId: Protocol.ItemId,
+  value: string,
+): Promise<void> {
+  const replica = store.get(activeNotebookReplicaAtom);
+  const notebook = replica === null ? null : store.get(replica.notebookAtom);
+  const backend = replica === null ? null : store.get(replica.backendAtom);
+  if (notebook === null || backend === null) {
+    Logger.warn("No notebook is connected to answer the prompt in");
+    return;
+  }
+  try {
+    const result = await backend
+      .notebook(notebook.id)
+      .input(inputId, { value });
+    if (result.ok) {
+      return;
+    }
+    Logger.error("The host refused the input reply", result.problem);
+    toast({
+      title: "Failed to send input",
+      description: result.problem.detail ?? result.problem.title,
+      variant: "danger",
+    });
+  } catch (error) {
+    Logger.error("Failed to send input", error);
+    toast({
+      title: "Failed to send input",
+      description: prettyError(error),
+      variant: "danger",
+    });
+  }
+}

package/src/core/executions/output.ts

@@ -0,0 +1,242 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/**
+ * What a cell shows in its output area, read from the host's executions.
+ *
+ * A completed result's outcome is the output. While the cell runs again,
+ * the running execution's value so far takes its place, so appended
+ * output appears as it arrives. The view keeps the message shape the
+ * renderers take, so they need not know where it came from.
+ */
+
+import type * as Protocol from "@marimo-team/client/protocol";
+import type { CellId } from "@/core/cells/ids";
+import type { MarimoError, OutputMessage } from "@/core/kernel/messages";
+import type { Executions, Results } from "@/core/notebook/replica";
+
+/** A host error shown as its message and the cells involved. */
+export interface HostDiagnostic {
+  readonly type: "diagnostic";
+  readonly kind: string;
+  readonly msg: string;
+  readonly related: readonly {
+    readonly cell_id: CellId;
+    readonly message: string;
+  }[];
+}
+
+/** An error the output area renders: a kernel shape or a host diagnostic. */
+export type CellError = MarimoError | HostDiagnostic;
+
+/** An output message whose error data may carry host diagnostics. */
+export type CellOutput = Omit<OutputMessage, "data"> & {
+  readonly data: OutputMessage["data"] | readonly CellError[];
+};
+
+/** What every cell's output derives from. */
+export interface CellOutputInputs {
+  readonly executions: Executions;
+  readonly results: Results;
+  /** Results this browser cleared, by execution id, until a newer one lands. */
+  readonly cleared: ReadonlyMap<Protocol.CellId, Protocol.ExecutionId>;
+}
+
+const ERROR_MIMETYPE = "application/vnd.marimo+error";
+
+/** The protocol's ids are plain strings; the editor brands them. */
+function brand(id: Protocol.CellId): CellId {
+  return id as CellId;
+}
+
+function related(
+  cells: readonly Protocol.Related[],
+): HostDiagnostic["related"] {
+  return cells.map(({ cell_id, message }) => ({
+    cell_id: brand(cell_id),
+    message,
+  }));
+}
+
+function seconds(iso: string | null): number {
+  return iso === null ? 0 : Date.parse(iso) / 1000;
+}
+
+function endedAt(record: Protocol.Execution): number {
+  return seconds(record.completed_at ?? record.started_at);
+}
+
+function valueOutput(
+  record: Protocol.Execution,
+  value: Protocol.DisplayData,
+): CellOutput {
+  return {
+    channel: "output",
+    mimetype: value.mimetype as OutputMessage["mimetype"],
+    data: value.data,
+    timestamp: endedAt(record),
+  };
+}
+
+function errorOutput(
+  record: Protocol.Execution,
+  data: CellError[],
+): CellOutput {
+  return {
+    channel: "marimo-error",
+    mimetype: ERROR_MIMETYPE,
+    data,
+    timestamp: endedAt(record),
+  };
+}
+
+/** The cell an exception was blamed on, when the host names one. */
+function raisingCell(error: Protocol.Error): CellId | null {
+  const raised = error.related.find((cell) => cell.message === "raised");
+  return raised === undefined ? null : brand(raised.cell_id);
+}
+
+/**
+ * A host error in the shape the output area renders.
+ *
+ * Exceptions, syntax errors, and internal errors keep the kernel's shapes,
+ * which the renderer treats with their own affordances. Every other kind
+ * is a diagnostic.
+ */
+export function cellError(error: Protocol.Error): CellError {
+  switch (error.kind) {
+    case "exception":
+      return {
+        type: "exception",
+        exception_type: error.name ?? "Exception",
+        msg: error.message,
+        raising_cell: raisingCell(error),
+        traceback: error.traceback?.data ?? null,
+      };
+    case "invalid-syntax":
+      return {
+        type: "syntax",
+        msg: error.message,
+        lineno: error.range === null ? null : error.range.start.line + 1,
+      };
+    case "internal":
+      return { type: "unknown", msg: error.message, error_type: error.name };
+    case "interrupted":
+      return { type: "interruption" };
+    default:
+      return {
+        type: "diagnostic",
+        kind: error.kind,
+        msg: error.message,
+        related: related(error.related),
+      };
+  }
+}
+
+/** The notice a skipped cell shows in place of a value. */
+function skippedOutput(
+  record: Protocol.Execution,
+  outcome: Protocol.SkippedOutcome,
+): CellOutput {
+  const cause = outcome.related[0];
+  if (cause !== undefined && outcome.reason === "upstream-stopped") {
+    return errorOutput(record, [
+      {
+        type: "ancestor-stopped",
+        msg: outcome.message,
+        raising_cell: brand(cause.cell_id),
+      },
+    ]);
+  }
+  if (cause !== undefined && outcome.reason === "upstream-failed") {
+    const blamed = outcome.related
+      .slice(1)
+      .find((cell) => cell.cell_id !== record.cell_id);
+    return errorOutput(record, [
+      {
+        type: "ancestor-prevented",
+        msg: outcome.message,
+        raising_cell: brand(cause.cell_id),
+        blamed_cell: blamed === undefined ? null : brand(blamed.cell_id),
+      },
+    ]);
+  }
+  return errorOutput(record, [
+    {
+      type: "diagnostic",
+      kind: outcome.reason,
+      msg: outcome.message,
+      related: related(outcome.related),
+    },
+  ]);
+}
+
+/** What an execution's outcome shows, or null for an empty value. */
+export function outcomeOutput(record: Protocol.Execution): CellOutput | null {
+  const outcome = record.outcome;
+  if (outcome === null) {
+    return null;
+  }
+  switch (outcome.kind) {
+    case "value":
+      return outcome.display === null
+        ? null
+        : valueOutput(record, outcome.display);
+    case "error":
+      return errorOutput(record, [cellError(outcome.error)]);
+    case "interrupted":
+      return errorOutput(record, [{ type: "interruption" }]);
+    case "skipped":
+      return skippedOutput(record, outcome);
+  }
+}
+
+/**
+ * What a cell shows: its running value so far, else its result's outcome.
+ *
+ * A running execution's outcome is null until it shows something, so the
+ * result stays up until then. Once it has shown, an empty display means
+ * the cell cleared its output, and nothing shows.
+ */
+export function cellOutputView(
+  inputs: CellOutputInputs,
+  id: Protocol.CellId,
+): CellOutput | null {
+  const latestId = inputs.executions.latest.get(id);
+  const latest =
+    latestId === undefined
+      ? undefined
+      : inputs.executions.executions.get(latestId)?.record;
+  if (latest !== undefined && latest.outcome !== null) {
+    if (latest.status !== "completed") {
+      return outcomeOutput(latest);
+    }
+  }
+  const result = inputs.results.get(id);
+  if (result === null || result === undefined) {
+    return null;
+  }
+  if (inputs.cleared.get(id) === result.id) {
+    return null;
+  }
+  return outcomeOutput(result);
+}
+
+/** What the scratchpad shows, from its latest scratch execution. */
+export function scratchOutputView(executions: Executions): CellOutput | null {
+  let scratch: Protocol.Execution | undefined;
+  for (const { record } of executions.executions.values()) {
+    if (record.cell_id !== null) {
+      continue;
+    }
+    if (
+      scratch === undefined ||
+      seconds(record.started_at) >= seconds(scratch.started_at)
+    ) {
+      scratch = record;
+    }
+  }
+  if (scratch === undefined) {
+    return null;
+  }
+  return outcomeOutput(scratch);
+}

package/src/core/executions/run.ts

@@ -0,0 +1,120 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/** Submit cell runs to the host. */
+
+import type * as Protocol from "@marimo-team/client/protocol";
+import type { createStore } from "jotai";
+import type { DocumentModel } from "@/core/notebook/document";
+import { toast } from "@/components/ui/use-toast";
+import { startRuntimeIfLazy } from "@/core/runtime/config";
+import { activeDocumentModelAtom } from "@/core/session/active-notebook";
+import { prettyError } from "@/utils/errors";
+import { Logger } from "@/utils/Logger";
+import {
+  acceptRun,
+  isCurrent,
+  requestRun,
+  waitForRuntimeRunning,
+  withdrawRequest,
+} from "./atoms";
+
+type Store = ReturnType<typeof createStore>;
+
+/**
+ * Start a lazy runtime and wait until the host reports it running.
+ *
+ * The host refuses a run while its runtime is not running, so a request
+ * made during startup waits here instead of failing. It rejects once the
+ * runtime cannot come up, so the request is not left waiting.
+ */
+export async function waitForRuntime(store: Store): Promise<void> {
+  await startRuntimeIfLazy();
+  await waitForRuntimeRunning(store);
+}
+
+/**
+ * Get this browser's edits to the host before a command that names cells.
+ *
+ * A run asks for the edits explicitly, so a synchronization that stalled
+ * earlier is retried here rather than left to the footer's retry.
+ */
+export function syncEdits(model: DocumentModel): Promise<Protocol.Document> {
+  return model.retry();
+}
+
+/**
+ * Run `cellIds` through the host once this browser's edits have reached it.
+ *
+ * The cells read as queued right away. When the host accepts the run, the
+ * stream shows it with the same cells named on it and takes over from the
+ * request. A request that never reaches the host is withdrawn, and the
+ * user is told why. The request belongs to the notebook it was made in, so
+ * if another notebook is shown by the time the edits have synced, it is
+ * dropped rather than sent there.
+ */
+export async function runCells(
+  store: Store,
+  cellIds: readonly Protocol.CellId[],
+): Promise<void> {
+  if (cellIds.length === 0) {
+    return;
+  }
+  const model = store.get(activeDocumentModelAtom);
+  if (model === null) {
+    Logger.warn("No notebook is open to run cells in");
+    return;
+  }
+  // The stream may have no notebook for a moment, as during a reconnect.
+  // The request is then recorded once the runtime, and with it the
+  // notebook, has been seen.
+  let request = requestRun(store, cellIds);
+  try {
+    await waitForRuntime(store);
+    request ??= requestRun(store, cellIds);
+    if (request === null) {
+      throw new Error("No notebook is shown");
+    }
+    const { notebook_id } = await syncEdits(model);
+    if (
+      store.get(activeDocumentModelAtom) !== model ||
+      !isCurrent(store, request) ||
+      notebook_id !== request.notebook.id
+    ) {
+      withdrawRequest(store, request);
+      return;
+    }
+    const backend = store.get(request.notebook.replica.backendAtom);
+    if (backend === null) {
+      throw new Error("The notebook is not connected");
+    }
+    const result = await backend
+      .notebook(notebook_id)
+      .run({ cells: cellIds.map((id) => ({ id })) });
+    if (result.ok) {
+      acceptRun(store, request, result.data);
+      return;
+    }
+    withdrawRequest(store, request);
+    // The connection is read-only for this action, which the UI shows.
+    if (result.status === 403) {
+      Logger.warn("Run refused, connection is read-only", result.problem);
+      return;
+    }
+    Logger.error("The host refused the run", result.problem);
+    toast({
+      title: "Failed to run",
+      description: result.problem.detail ?? result.problem.title,
+      variant: "danger",
+    });
+  } catch (error) {
+    if (request !== null) {
+      withdrawRequest(store, request);
+    }
+    Logger.error("Failed to run cells", error);
+    toast({
+      title: "Failed to run",
+      description: prettyError(error),
+      variant: "danger",
+    });
+  }
+}

package/src/core/executions/select.ts

@@ -0,0 +1,210 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/** Pure views over the replica's executions and results, by cell. */
+
+import type * as Protocol from "@marimo-team/client/protocol";
+import type { Execution, Executions, Results } from "@/core/notebook/replica";
+import { type Milliseconds, Time } from "@/utils/time";
+
+/** Where a cell is in its run. */
+export type CellRunStatus = "idle" | "queued" | "running";
+
+/** How a cell's last completed execution ended. */
+export type CellOutcome = "value" | "error" | "interrupted" | "skipped";
+
+export interface CellExecutionView {
+  readonly status: CellRunStatus;
+  /** Whether a cell it depends on is disabled, so it cannot run. */
+  readonly blocked: boolean;
+  /** Null until the cell completes once, and while it runs again. */
+  readonly outcome: CellOutcome | null;
+  /** When the current run started, or the last one, since the epoch. */
+  readonly startedAt: Milliseconds | null;
+  /** How long the last completed execution took, null while the cell runs again. */
+  readonly duration: Milliseconds | null;
+  /** Whether the running execution has shown a value so far. TODO(MO-8404) */
+  readonly rendered: boolean;
+}
+
+/** What a cell's view is derived from. */
+export interface CellExecutionInputs {
+  readonly executions: Executions;
+  readonly results: Results;
+  /**
+   * The cells of the confirmed document. A run can only reach a cell the
+   * document has, and the kernel sets aside one the document has disabled.
+   */
+  readonly cells: ReadonlyMap<Protocol.CellId, Pick<Protocol.Cell, "config">>;
+  /**
+   * Cells this browser has asked to run, while the stream has not yet
+   * shown the run.
+   */
+  readonly requested: ReadonlySet<Protocol.CellId>;
+  /** Cells the kernel reports as blocked by a disabled ancestor. */
+  readonly blocked: ReadonlySet<Protocol.CellId>;
+}
+
+export function outcomeOf(record: Protocol.Execution): CellOutcome | null {
+  const outcome = record.outcome;
+  if (outcome === null) {
+    return null;
+  }
+  return outcome.kind;
+}
+
+function millis(iso: string | null): Milliseconds | null {
+  return iso === null ? null : Time.parse(iso).toMilliseconds();
+}
+
+function latestOf(
+  executions: Executions,
+  id: Protocol.CellId,
+): Execution | null {
+  const executionId = executions.latest.get(id);
+  return executionId === undefined
+    ? null
+    : (executions.executions.get(executionId) ?? null);
+}
+
+/**
+ * Whether a run can reach `id`, meaning the document has the cell and
+ * nothing keeps it from running.
+ */
+function runnable(inputs: CellExecutionInputs, id: Protocol.CellId): boolean {
+  const cell = inputs.cells.get(id);
+  return cell !== undefined && !cell.config.disabled && !inputs.blocked.has(id);
+}
+
+/**
+ * Whether `id` is waiting on a run that has not planned an execution for
+ * it yet.
+ *
+ * When the host accepts a run it names the cells that were requested, and
+ * this happens before the kernel plans their executions. Until the cell's
+ * execution in that run appears, the run itself is what makes the cell
+ * queued. A request this browser has made works the same way until its
+ * run shows up on the stream. The host keeps one execution per cell, so
+ * the cell's latest execution, or its retained result once the stream has
+ * let that execution go, tells which run has already planned it.
+ */
+function awaited(inputs: CellExecutionInputs, id: Protocol.CellId): boolean {
+  if (!runnable(inputs, id)) {
+    return false;
+  }
+  if (inputs.requested.has(id)) {
+    return true;
+  }
+  const planned =
+    latestOf(inputs.executions, id)?.record.run_id ??
+    inputs.results.get(id)?.run_id;
+  for (const run of inputs.executions.runs.values()) {
+    if (
+      run.status !== "completed" &&
+      run.id !== planned &&
+      run.cells.includes(id)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function cellExecutionView(
+  inputs: CellExecutionInputs,
+  id: Protocol.CellId,
+): CellExecutionView {
+  const latest = latestOf(inputs.executions, id);
+  const result = inputs.results.get(id) ?? null;
+  let status: CellRunStatus = "idle";
+  let startedAt = result === null ? null : millis(result.started_at);
+  let rendered = false;
+  if (latest !== null && latest.record.status !== "completed") {
+    status = latest.record.status;
+    startedAt = millis(latest.record.started_at) ?? startedAt;
+    rendered = latest.record.outcome !== null;
+  } else if (awaited(inputs, id)) {
+    status = "queued";
+  }
+  const settled = status === "idle";
+  const duration =
+    settled &&
+    result !== null &&
+    result.started_at !== null &&
+    result.completed_at !== null
+      ? Time.parse(result.completed_at).since(Time.parse(result.started_at))
+      : null;
+  return {
+    status,
+    blocked: inputs.blocked.has(id),
+    outcome: settled && result !== null ? outcomeOf(result) : null,
+    startedAt,
+    duration,
+    rendered,
+  };
+}
+
+/** Executions the host has not completed, cells and scratch alike. */
+function unfinished(executions: Executions): Execution[] {
+  return [...executions.executions.values()].filter(
+    (execution) => execution.record.status !== "completed",
+  );
+}
+
+export function anyRunning(executions: Executions): boolean {
+  return unfinished(executions).some(
+    (execution) => execution.record.status === "running",
+  );
+}
+
+/** Cells and scratch work queued or running, plus cells awaiting a run the kernel has not planned. */
+export function queuedOrRunningCount(inputs: CellExecutionInputs): number {
+  const pending = unfinished(inputs.executions);
+  const shown = new Set(
+    pending.flatMap((execution) =>
+      execution.record.cell_id === null ? [] : [execution.record.cell_id],
+    ),
+  );
+  const named = new Set<Protocol.CellId>(inputs.requested);
+  for (const run of inputs.executions.runs.values()) {
+    if (run.status !== "completed") {
+      for (const cellId of run.cells) {
+        named.add(cellId);
+      }
+    }
+  }
+  let awaiting = 0;
+  for (const cellId of named) {
+    if (!shown.has(cellId) && awaited(inputs, cellId)) {
+      awaiting += 1;
+    }
+  }
+  return pending.length + awaiting;
+}
+
+export function onlyScratchRunning(executions: Executions): boolean {
+  return unfinished(executions).every(
+    (execution) =>
+      execution.record.status !== "running" ||
+      execution.record.cell_id === null,
+  );
+}
+
+/** Where the scratchpad's work is, from its unfinished execution if any. */
+export function scratchStatus(executions: Executions): CellRunStatus {
+  const scratch = unfinished(executions).find(
+    (execution) => execution.record.cell_id === null,
+  );
+  if (scratch === undefined || scratch.record.status === "completed") {
+    return "idle";
+  }
+  return scratch.record.status;
+}
+
+/** Cells with a running execution, in the order the host reported them. */
+export function runningCellIds(executions: Executions): Protocol.CellId[] {
+  return unfinished(executions).flatMap((execution) =>
+    execution.record.status === "running" && execution.record.cell_id !== null
+      ? [execution.record.cell_id]
+      : [],
+  );
+}

package/src/core/export/__tests__/hooks.test.ts

@@ -67,11 +67,6 @@ describe("useEnrichCellOutputs", () => {
         cellId,
         {
           output: cell.output || null,
-          status: cell.status || "idle",
-          interrupted: false,
-          errored: false,
-          runStartTimestamp: null,
-          runElapsedTimeMs: null,
           stallTime: null as unknown as number,
           ...cell,
         } as CellRuntimeState,

package/src/core/export/hooks.ts

@@ -16,7 +16,7 @@ import { connectionAtom } from "../network/connection";
 import { useRequestClient } from "../network/requests";
 import type { UpdateCellOutputsRequest } from "../network/types";
 import { VirtualFileTracker } from "../static/virtual-file-tracker";
-import { ConnectionState } from "../websocket/types";
+import { ConnectionState } from "../session/types";
 
 const DELAY = 5000; // 5 seconds;
 

package/src/core/export/layout.ts

@@ -1,9 +1,9 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
-import { flushDocumentChanges } from "@/core/cells/document-changes";
+import { flushDocument } from "@/core/cells/document";
 import { getSerializedLayout } from "@/core/layout/layout";
 
 export async function getExportLayout() {
-  await flushDocumentChanges();
+  await flushDocument();
   return getSerializedLayout();
 }

package/src/core/hotkeys/actions.ts

@@ -2,6 +2,7 @@
 import { atom, useAtomValue, useSetAtom } from "jotai";
 import useEvent from "react-use-event-hook";
 import type { HotkeyAction } from "@/core/hotkeys/hotkeys";
+import { Objects } from "@/utils/objects";
 
 /**
  * Map of registered keyboard shortcuts and their callbacks.
@@ -29,10 +30,7 @@ export function useSetRegisteredAction() {
       },
     ),
     unregisterAction: useEvent((shortcut: HotkeyAction) => {
-      set((actions) => {
-        const { [shortcut]: unused, ...rest } = actions;
-        return rest;
-      });
+      set((actions) => Objects.omit(actions, [shortcut]));
     }),
   };
 }

package/src/core/hotkeys/hotkeys.ts

@@ -221,7 +221,8 @@ const DEFAULT_HOT_KEY = {
     key: "Mod-h",
   },
   "cell.aiCompletion": {
-    name: "AI completion",
+    name: "Refactor cell",
+    additionalKeywords: ["AI", "AI completion"],
     group: "Editing",
     key: "Mod-Shift-e",
   },