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

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/select.ts

@@ -0,0 +1,175 @@
+/* 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 execution each submitted cell had when its run was requested.
+   *
+   * A cell reads as queued until the host shows a newer execution for it.
+   */
+  readonly submissions: ReadonlyMap<
+    Protocol.CellId,
+    Protocol.ExecutionId | null
+  >;
+  /** 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);
+}
+
+/**
+ * The execution a submission is measured against: the cell's latest on the
+ * stream, or its retained result once the stream has let that execution go.
+ */
+export function latestExecutionId(
+  inputs: Pick<CellExecutionInputs, "executions" | "results">,
+  id: Protocol.CellId,
+): Protocol.ExecutionId | null {
+  return inputs.executions.latest.get(id) ?? inputs.results.get(id)?.id ?? null;
+}
+
+export function cellExecutionView(
+  inputs: CellExecutionInputs,
+  id: Protocol.CellId,
+): CellExecutionView {
+  const latest = latestOf(inputs.executions, id);
+  const result = inputs.results.get(id) ?? null;
+  const submitted =
+    inputs.submissions.has(id) &&
+    inputs.submissions.get(id) === latestExecutionId(inputs, id);
+  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 (submitted) {
+    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 submissions the host has not shown yet. */
+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],
+    ),
+  );
+  let awaiting = 0;
+  for (const [cellId, executionId] of inputs.submissions) {
+    if (
+      !shown.has(cellId) &&
+      executionId === latestExecutionId(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",
   },

package/src/core/islands/__tests__/bootstrap.test.ts

@@ -1,22 +1,29 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
+import type { NotebookTransport } from "@marimo-team/client";
 import { createStore } from "jotai";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { cellId } from "@/__tests__/branded";
+import { notebookAtom } from "@/core/cells/cells";
+import {
+  fakeBackend,
+  fixtureMessages,
+} from "@/core/notebook/replica/__tests__/fixtures";
 import { RuntimeState } from "@/core/kernel/RuntimeState";
 import { initializeIslands } from "../bootstrap";
 import type { IslandsPyodideBridge } from "../bridge";
 import { islandsHydratedAtom, islandsPendingInitialRunsAtom } from "../state";
-import type { IslandsKernelMessage } from "../worker/worker";
-
-function completedRun(sessionGeneration: number): IslandsKernelMessage {
-  return {
-    sessionGeneration,
-    message: JSON.stringify({
-      op: "completed-run",
-      data: { op: "completed-run", run_id: null },
-    }) as IslandsKernelMessage["message"],
-  };
-}
+import type { NotificationMessage } from "@/core/kernel/messages";
+
+type Consumer = (
+  notification: NotificationMessage,
+  sessionGeneration: number,
+) => void;
+
+const completedRun = {
+  op: "completed-run",
+  run_id: null,
+} as NotificationMessage;
 
 describe("initializeIslands", () => {
   afterEach(vi.restoreAllMocks);
@@ -26,12 +33,13 @@ describe("initializeIslands", () => {
     root.innerHTML =
       '<marimo-island data-app-id="app-1" data-reactive="true"></marimo-island>';
 
-    let consumeMessage: ((message: IslandsKernelMessage) => void) | undefined;
+    let consumeMessage: Consumer | undefined;
     const bridge = {
-      consumeMessages: (consumer: (message: IslandsKernelMessage) => void) => {
+      consumeNotifications: (consumer: Consumer) => {
         consumeMessage = consumer;
       },
       sendComponentValues: vi.fn(),
+      notebookBackend: fakeBackend(),
     } as unknown as IslandsPyodideBridge;
     const store = createStore();
     vi.spyOn(RuntimeState.INSTANCE, "start").mockImplementation(
@@ -48,14 +56,58 @@ describe("initializeIslands", () => {
     expect(store.get(islandsHydratedAtom)).toBe(false);
     store.set(islandsPendingInitialRunsAtom, new Set([1, 2]));
 
-    consumeMessage?.(completedRun(1));
+    consumeMessage?.(completedRun, 1);
     expect(store.get(islandsHydratedAtom)).toBe(false);
 
-    consumeMessage?.(completedRun(1));
-    consumeMessage?.(completedRun(0));
+    consumeMessage?.(completedRun, 1);
+    consumeMessage?.(completedRun, 0);
     expect(store.get(islandsHydratedAtom)).toBe(false);
 
-    consumeMessage?.(completedRun(2));
+    consumeMessage?.(completedRun, 2);
     expect(store.get(islandsHydratedAtom)).toBe(true);
   });
 });
+
+describe("initializeIslands document", () => {
+  afterEach(vi.restoreAllMocks);
+
+  it("fills the notebook's cells from the managed session's host document", async () => {
+    const root = document.createElement("div");
+    root.innerHTML =
+      '<marimo-island data-app-id="app-1" data-reactive="true"></marimo-island>';
+    let handlers: Parameters<NotebookTransport>[1] | undefined;
+    const transport: NotebookTransport = (_attempt, opened) =>
+      new Promise(() => {
+        handlers = opened;
+        opened.open();
+      });
+    const bridge = {
+      consumeNotifications: vi.fn(),
+      sendComponentValues: vi.fn(),
+      notebookBackend: fakeBackend({ transport }),
+    } as unknown as IslandsPyodideBridge;
+    const store = createStore();
+    vi.spyOn(RuntimeState.INSTANCE, "start").mockImplementation(
+      () => undefined,
+    );
+
+    await initializeIslands({
+      bridge,
+      store,
+      root,
+      autoInitializePlugins: false,
+    });
+    await vi.waitFor(() => expect(handlers).toBeDefined());
+    for (const message of fixtureMessages("notebook-events.sse")) {
+      handlers?.message(message);
+    }
+
+    const notebook = store.get(notebookAtom);
+    expect(notebook.cellIds).toEqual(["c1", "c3", "k7f2"]);
+    expect(notebook.cellData[cellId("c3")].code).toBe("x = 21");
+    expect(notebook.cellRuntime[cellId("c3")]).toBeDefined();
+
+    handlers?.message({ event: "reset", data: {} });
+    expect(store.get(notebookAtom).cellIds).toEqual(["c1", "c3", "k7f2"]);
+  });
+});