@marimo-team/islands 0.25.3-dev5 → 0.25.3-dev51

package/src/core/host/events.ts

@@ -0,0 +1,68 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { z } from "zod";
+import * as Protocol from "@marimo-team/client/protocol";
+
+/**
+ * Notebook stream events, including native marimo notifications.
+ *
+ * Known events follow the generated protocol. Unknown events retain their name
+ * and cursor so clients can skip them without losing their place in the stream.
+ */
+
+const envelope = z.object({
+  event: z.string().min(1),
+  data: z.unknown(),
+  id: z.string().min(1).optional(),
+});
+
+const knownNames = new Set<string>(
+  Protocol.Event.options.flatMap((schema) => schema.shape.event.options),
+);
+
+/**
+ * A native marimo message carried by a host stream.
+ *
+ * The protocol leaves extension events to their producer. The payload is
+ * passed through for the session handler to interpret.
+ */
+const MarimoEvent = z.object({
+  event: z.literal("marimo"),
+  id: z.string().min(1).optional(),
+  data: z.object({ marimo: z.unknown() }),
+});
+
+/** A decoded event, or the name and cursor of an unrecognized event. */
+export type NotebookEvent =
+  | Protocol.EventOutput
+  | z.output<typeof MarimoEvent>
+  | {
+      readonly event: "unknown";
+      readonly name: string;
+      readonly id?: string;
+    };
+
+const sessionEnvelope = z.object({ data: z.unknown() });
+
+/**
+ * Decode a host event or an in-process WASM `{ data: notification }` message.
+ *
+ * Throws if the envelope or a known event is malformed. Native notification
+ * payloads are passed through for the session handler to interpret.
+ */
+export function parseNotebookEvent(value: unknown): NotebookEvent {
+  if (typeof value === "object" && value !== null && !("event" in value)) {
+    return {
+      event: "marimo",
+      data: { marimo: sessionEnvelope.parse(value).data },
+    };
+  }
+  const parsed = envelope.parse(value);
+  if (parsed.event === "marimo") {
+    return MarimoEvent.parse(parsed);
+  }
+  if (knownNames.has(parsed.event)) {
+    return Protocol.Event.parse(parsed);
+  }
+  return { event: "unknown", name: parsed.event, id: parsed.id };
+}

package/src/core/host/notebook-client.ts

@@ -0,0 +1,316 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { Logger } from "@/utils/Logger";
+import type { Attachment, NotebookOutput } from "@marimo-team/client/protocol";
+import { createReducer } from "@marimo-team/client/reducer";
+import { type Atom, atom, type createStore } from "jotai/vanilla";
+import {
+  type ConnectionStatus,
+  ConnectionState,
+  ConnectionClosedReason,
+  type CloseDecision,
+  type NotebookTransport,
+  TransportReadyState,
+} from "./connection";
+import { type NotebookEvent, parseNotebookEvent } from "./events";
+import { attachments } from "./resources/attachments";
+import { type Document, document } from "./resources/document";
+
+/** Events that may arrive without a cursor after `ready`. */
+const UNCURSORED = new Set<NotebookEvent["event"]>([
+  "reset",
+  "marimo",
+  "unknown",
+]);
+
+/** A connection to a notebook on a marimo host. */
+export interface NotebookClient {
+  /** Client connection status, independent of application session readiness. */
+  readonly connectionAtom: Atom<ConnectionStatus>;
+  /** Identity and capabilities, available while the stream is connected and ready. */
+  readonly notebookAtom: Atom<NotebookOutput | null>;
+  /**
+   * The most recently confirmed document.
+   *
+   * Null until a snapshot is complete, after reset or removal, and on
+   * connections without host document events. A temporary disconnection
+   * retains the last document. Partial updates are not exposed.
+   */
+  readonly documentAtom: Atom<Document | null>;
+  /** Live attachments, empty until the stream is ready or while disconnected. */
+  readonly attachmentsAtom: Atom<readonly Attachment[]>;
+  /** Attempt to restore a closed connection after checking host health. */
+  reconnect(): Promise<void>;
+}
+
+/** The transport and application callbacks needed to connect a notebook. */
+export interface NotebookConnection {
+  /** Create a transport that reads the URL again on each connection attempt. */
+  createTransport: (url: () => string) => NotebookTransport;
+  /** The current stream URL, including authentication and subscription options. */
+  url: () => string;
+  /** Abort to close the transport and clear the client's state. */
+  signal: AbortSignal;
+  /** Wait until the host can accept the initial connection. */
+  waitUntilReady: () => Promise<void>;
+  /** Check whether the host is reachable before an explicit reconnect. */
+  checkHealth: () => Promise<boolean>;
+  /** Decode wire text without interpreting its event type. */
+  decodeJson: (message: string) => unknown;
+  /** Handle a native marimo notification. Its payload has not been validated. */
+  onNotification: (notification: unknown) => void;
+  /** Choose the connection status and retry policy after the transport closes. */
+  classifyClose: (event: CloseEvent) => CloseDecision;
+}
+
+/** Create a client without opening a connection. */
+export function createNotebookClient(store: ReturnType<typeof createStore>) {
+  const connectionAtom = atom<ConnectionStatus>({
+    state: ConnectionState.NOT_STARTED,
+  });
+  // One atom holds the whole stream, which resource atoms derive from.
+  const reducer = createReducer({ document, attachments });
+  const streamAtom = atom(reducer.initial);
+  // A resumed stream is live, but presence waits for this connection's ready.
+  const readyAtom = atom(false);
+  const notebookAtom = atom((get) =>
+    get(readyAtom) && get(connectionAtom).state === ConnectionState.OPEN
+      ? get(streamAtom).notebook
+      : null,
+  );
+  const documentAtom = atom(
+    (get) => get(streamAtom).resources.document.current,
+  );
+  const attachmentsAtom = atom((get) =>
+    get(readyAtom) && get(connectionAtom).state === ConnectionState.OPEN
+      ? get(streamAtom).resources.attachments
+      : attachments.initial,
+  );
+  let reconnect: (() => Promise<void>) | undefined;
+  const client: NotebookClient = {
+    connectionAtom,
+    notebookAtom,
+    documentAtom,
+    attachmentsAtom,
+    reconnect: async () => reconnect?.(),
+  };
+
+  function connect({
+    createTransport,
+    url,
+    signal,
+    waitUntilReady,
+    checkHealth,
+    onNotification,
+    decodeJson,
+    classifyClose,
+  }: NotebookConnection) {
+    if (signal.aborted) {
+      return;
+    }
+    let shouldRetry = true;
+    let terminal = false;
+    let checkingHealth = false;
+    let streamKey: string | undefined;
+    // The id of the last live event. Null before `ready` and after `reset`.
+    let cursor: string | null = null;
+    const transport = createTransport(() => {
+      const next = new URL(url());
+      next.searchParams.delete("cursor");
+      if (signal.aborted) {
+        return next.toString();
+      }
+      // A cursor is useful with the state that produced it, which a change
+      // of session or notebook invalidates. Authentication may change freely.
+      const identity = new URL(next);
+      identity.searchParams.delete("access_token");
+      identity.searchParams.sort();
+      const key = identity.toString();
+      const current = store.get(streamAtom);
+      // A live stream keeps its state and resumes from the cursor. An
+      // incomplete snapshot starts over.
+      const state =
+        key !== streamKey || current.phase === "snapshot"
+          ? reducer.initial
+          : current;
+      if (state.phase === "snapshot") {
+        cursor = null;
+      }
+      streamKey = key;
+      store.set(readyAtom, false);
+      store.set(streamAtom, state);
+      if (cursor !== null) {
+        next.searchParams.set("cursor", cursor);
+      }
+      return next.toString();
+    });
+    const setStatus = (status: ConnectionStatus) => {
+      store.set(readyAtom, false);
+      store.set(connectionAtom, status);
+    };
+    const disconnected = {
+      state: ConnectionState.CLOSED,
+      code: ConnectionClosedReason.KERNEL_DISCONNECTED,
+      reason: "kernel not found",
+    } satisfies ConnectionStatus;
+
+    function retry(code?: number, reason?: string) {
+      if (!signal.aborted && !terminal && shouldRetry) {
+        shouldRetry = false;
+        transport.reconnect(code, reason);
+      }
+    }
+
+    function onOpen() {
+      if (signal.aborted || terminal) {
+        return;
+      }
+      shouldRetry = true;
+      setStatus({ state: ConnectionState.OPEN });
+    }
+
+    function onClose(event: CloseEvent) {
+      if (signal.aborted || terminal) {
+        return;
+      }
+      Logger.warn("Notebook connection closed", event.code, event.reason);
+      const decision = classifyClose(event);
+      setStatus(decision.status);
+      if (decision.kind === "terminal") {
+        terminal = true;
+        transport.close();
+      } else if (decision.kind === "retry") {
+        retry(event.code, event.reason);
+      } else {
+        terminal = true;
+      }
+    }
+
+    function onError(event: Event) {
+      if (signal.aborted || terminal) {
+        return;
+      }
+      Logger.warn("Notebook connection error", event);
+      setStatus(disconnected);
+      retry();
+    }
+
+    function onMessage(message: MessageEvent<string>) {
+      if (signal.aborted || terminal) {
+        return;
+      }
+      let event;
+      try {
+        event = parseNotebookEvent(decodeJson(message.data));
+        const state = store.get(streamAtom);
+        if (
+          state.phase === "live" &&
+          event.id === undefined &&
+          !UNCURSORED.has(event.event)
+        ) {
+          throw new Error("Live notebook event is missing its cursor");
+        }
+        if (event.event !== "marimo" && event.event !== "unknown") {
+          store.set(streamAtom, reducer.reduce(state, event));
+        }
+        if (event.event === "reset") {
+          cursor = null;
+        } else if (event.event === "ready" || state.phase === "live") {
+          cursor = event.id ?? cursor;
+        }
+        if (event.event === "ready" || event.event === "reset") {
+          store.set(readyAtom, event.event === "ready");
+        }
+      } catch (error) {
+        Logger.error("Failed to decode notebook message", error);
+        store.set(streamAtom, reducer.initial);
+        cursor = null;
+        terminal = true;
+        setStatus({
+          ...disconnected,
+          reason: "Failed to decode notebook message",
+        });
+        transport.close();
+        return;
+      }
+      if (event.event === "marimo") {
+        onNotification(event.data.marimo);
+      }
+    }
+
+    reconnect = async () => {
+      if (
+        signal.aborted ||
+        checkingHealth ||
+        transport.readyState === TransportReadyState.OPEN ||
+        transport.readyState === TransportReadyState.CONNECTING
+      ) {
+        return;
+      }
+      checkingHealth = true;
+      setStatus({ state: ConnectionState.CONNECTING });
+      try {
+        const healthy = await checkHealth();
+        if (signal.aborted) {
+          return;
+        }
+        if (!healthy) {
+          shouldRetry = false;
+          setStatus(disconnected);
+          return;
+        }
+        terminal = false;
+        shouldRetry = true;
+        transport.reconnect();
+      } catch (error) {
+        if (!signal.aborted) {
+          Logger.error("Notebook health check failed", error);
+          shouldRetry = false;
+          setStatus(disconnected);
+        }
+      } finally {
+        checkingHealth = false;
+      }
+    };
+
+    signal.addEventListener(
+      "abort",
+      () => {
+        transport.removeEventListener("open", onOpen);
+        transport.removeEventListener("close", onClose);
+        transport.removeEventListener("error", onError);
+        transport.removeEventListener("message", onMessage);
+        transport.close();
+        reconnect = undefined;
+        store.set(streamAtom, reducer.initial);
+        setStatus({ state: ConnectionState.NOT_STARTED });
+      },
+      { once: true },
+    );
+
+    transport.addEventListener("open", onOpen);
+    transport.addEventListener("close", onClose);
+    transport.addEventListener("error", onError);
+    transport.addEventListener("message", onMessage);
+
+    if (transport.readyState === TransportReadyState.CLOSED) {
+      setStatus({ state: ConnectionState.CONNECTING });
+      void waitUntilReady()
+        .then(() => {
+          if (!signal.aborted) {
+            transport.reconnect();
+          }
+        })
+        .catch((error) => {
+          if (!signal.aborted) {
+            Logger.error("Healthy connection never made", error);
+            terminal = true;
+            setStatus(disconnected);
+            transport.close();
+          }
+        });
+    }
+  }
+
+  return { client, connect };
+}

package/src/core/host/resources/attachments.ts

@@ -0,0 +1,19 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type { Attachment } from "@marimo-team/client/protocol";
+import type { Resource } from "@marimo-team/client/reducer";
+
+/** Attachment records retained with the stream's resume cursor. */
+export const attachments: Resource<readonly Attachment[], "attachment"> = {
+  initial: [],
+  on: {
+    attachment: (state, { data: { attachment } }) =>
+      state.some((item) => item.id === attachment.id)
+        ? state.map((item) => (item.id === attachment.id ? attachment : item))
+        : [...state, attachment],
+    "attachment.removed": (state, { data }) =>
+      state.some((item) => item.id === data.id)
+        ? state.filter((item) => item.id !== data.id)
+        : state,
+  },
+};

package/src/core/host/resources/document.ts

@@ -0,0 +1,101 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type * as Protocol from "@marimo-team/client/protocol";
+import type { Resource } from "@marimo-team/client/reducer";
+
+/**
+ * The notebook's content at one revision.
+ *
+ * The revision record carries the cell order, app config, etags, and
+ * version. Each cell in its order has a record in `cells`.
+ */
+export interface Document {
+  readonly revision: Protocol.Document;
+  readonly cells: ReadonlyMap<Protocol.CellId, Protocol.Cell>;
+}
+
+/** The records of a revision still being received. */
+interface PendingDocument {
+  /** Null until the `document` event that closes the group arrives. */
+  readonly revision: Protocol.Document | null;
+  readonly cells: ReadonlyMap<Protocol.CellId, Protocol.Cell>;
+}
+
+/**
+ * The confirmed document and the revision being assembled after it.
+ *
+ * A snapshot's records are pending until `ready`. A live revision is pending
+ * from its first cell until its `document` event.
+ */
+interface DocumentState {
+  readonly current: Document | null;
+  readonly pending: PendingDocument | null;
+}
+
+function pendingOf(state: DocumentState): PendingDocument {
+  return (
+    state.pending ?? {
+      revision: state.current?.revision ?? null,
+      cells: state.current?.cells ?? new Map(),
+    }
+  );
+}
+
+/** Confirm a revision whose records are complete. */
+function publish(
+  revision: Protocol.Document,
+  cells: ReadonlyMap<Protocol.CellId, Protocol.Cell>,
+): DocumentState {
+  const order = new Set(revision.order);
+  if (
+    order.size !== revision.order.length ||
+    order.size !== cells.size ||
+    [...order].some((id) => !cells.has(id)) ||
+    [...cells.values()].some((cell) => cell.version > revision.version)
+  ) {
+    throw new Error("Document records do not match its revision and order");
+  }
+  return { current: { revision, cells }, pending: null };
+}
+
+export const document: Resource<DocumentState, "cell" | "document"> = {
+  initial: { current: null, pending: null },
+  on: {
+    cell: (state, { data }) => {
+      const pending = pendingOf(state);
+      return {
+        ...state,
+        pending: {
+          revision: pending.revision,
+          cells: new Map(pending.cells).set(data.cell.id, data.cell),
+        },
+      };
+    },
+    "cell.removed": (state, { data }) => {
+      const pending = pendingOf(state);
+      if (!pending.cells.has(data.id)) {
+        return state;
+      }
+      const cells = new Map(pending.cells);
+      cells.delete(data.id);
+      return { ...state, pending: { ...pending, cells } };
+    },
+    document: (state, { data }, { phase }) => {
+      const { cells } = pendingOf(state);
+      return phase === "snapshot"
+        ? { ...state, pending: { revision: data.document, cells } }
+        : publish(data.document, cells);
+    },
+    ready: (state, _event, { phase }) => {
+      if (state.pending === null) {
+        return state;
+      }
+      if (phase === "live") {
+        throw new Error("Stream ended with an incomplete document update");
+      }
+      return state.pending.revision === null
+        ? { current: null, pending: null }
+        : publish(state.pending.revision, state.pending.cells);
+    },
+  },
+};

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/islands/__tests__/bootstrap.test.ts

@@ -3,8 +3,6 @@
 import { createStore } from "jotai";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { RuntimeState } from "@/core/kernel/RuntimeState";
-import { attachmentsAtom } from "@/core/attachments/state";
-import { Logger } from "@/utils/Logger";
 import { initializeIslands } from "../bootstrap";
 import type { IslandsPyodideBridge } from "../bridge";
 import { islandsHydratedAtom, islandsPendingInitialRunsAtom } from "../state";
@@ -50,30 +48,6 @@ describe("initializeIslands", () => {
     expect(store.get(islandsHydratedAtom)).toBe(false);
     store.set(islandsPendingInitialRunsAtom, new Set([1, 2]));
 
-    const errors = vi.spyOn(Logger, "error");
-    consumeMessage?.({
-      sessionGeneration: 1,
-      message: JSON.stringify({
-        op: "attachments",
-        data: {
-          op: "attachments",
-          attachments: [
-            {
-              id: "a1",
-              kind: "agent",
-              name: "Pi",
-              since: "2026-10-14T00:00:00Z",
-              notebook_id: "nb-test",
-              identity: "pi-thread",
-            },
-          ],
-        },
-      }) as IslandsKernelMessage["message"],
-    });
-    expect(errors).not.toHaveBeenCalled();
-    expect(store.get(attachmentsAtom)).toEqual([]);
-    expect(store.get(islandsPendingInitialRunsAtom)).toEqual(new Set([1, 2]));
-
     consumeMessage?.(completedRun(1));
     expect(store.get(islandsHydratedAtom)).toBe(false);
 

package/src/core/islands/bootstrap.ts

@@ -209,7 +209,6 @@ function handleMessage(
       case "cache-info":
       case "kernel-startup-error":
       case "notebook-document-transaction":
-      case "attachments":
         return;
 
       case "completed-run":

package/src/core/network/connection.ts

@@ -7,8 +7,10 @@ import { waitFor } from "../state/jotai";
 import { type ConnectionStatus, ConnectionState } from "../websocket/types";
 
 /**
- * Atom for storing the connection status.
- * Initialized to NOT_STARTED.
+ * Shared application state, not the actual event-stream status.
+ *
+ * TODO(MO-8051) Expose read-only connection state and derive UI availability
+ * separately.
  */
 export const connectionAtom = atom<ConnectionStatus>({
   state: ConnectionState.NOT_STARTED,

package/src/core/run-app.tsx

@@ -22,7 +22,7 @@ import { getSessionId } from "./kernel/session";
 import { connectionAtom } from "./network/connection";
 import { useRequestClient } from "./network/requests";
 import { isAppConnecting } from "./websocket/connection-utils";
-import { useMarimoKernelConnection } from "./websocket/useMarimoKernelConnection";
+import { useNotebookSession } from "./websocket/useNotebookSession";
 
 interface AppProps {
   appConfig: AppConfig;
@@ -51,7 +51,7 @@ export const RunApp: React.FC<AppProps> = ({ appConfig, hideHeader }) => {
     };
   }, []);
 
-  const { connection, reconnect } = useMarimoKernelConnection({
+  const { connection, reconnect } = useNotebookSession({
     autoInstantiate: true,
     setCells: setCells,
     sessionId: getSessionId(),

package/src/core/runtime/__tests__/runtime.test.ts

@@ -8,8 +8,9 @@ import { RuntimeManager } from "../runtime";
 import type { RuntimeConfig } from "../types";
 
 // Mock the session module
-vi.mock("@/core/kernel/session", () => ({
-  getSessionId: () => "test-session-id" as SessionId,
+vi.mock("@/core/kernel/session", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@/core/kernel/session")>()),
+  getSessionId: () => "test-session-id",
 }));
 
 vi.mock("@/utils/Logger", () => ({ Logger: Mocks.quietLogger() }));
@@ -59,6 +60,7 @@ describe("RuntimeManager", () => {
       expect(url.protocol).toBe("wss:");
       expect(url.hostname).toBe("example.com");
       expect(url.pathname).toBe("/ws");
+      expect(url.searchParams.has("types")).toBe(false);
       expect(url.searchParams.get("session_id")).toBe(sessionId);
     });
 
@@ -219,15 +221,6 @@ describe("RuntimeManager", () => {
   });
 
   describe("getSseURL", () => {
-    it("should return an http(s) URL with the session ID", () => {
-      const runtime = new RuntimeManager(mockConfig);
-      const url = runtime.getSseURL("1234" as SessionId);
-
-      expect(url.protocol).toBe("https:");
-      expect(url.pathname).toBe("/sse");
-      expect(url.searchParams.get("session_id")).toBe("1234");
-    });
-
     it("should never put the auth token in the URL, even cross-origin", () => {
       // SSE requests can send headers, so auth travels in the
       // Authorization header; a token in the URL would leak into
@@ -737,7 +730,7 @@ describe("RuntimeManager", () => {
       );
     });
 
-    it("should throw when creating WebSocket URLs from blob URLs", () => {
+    it("warns when creating WebSocket URLs from blob URLs", () => {
       const runtime = new RuntimeManager({
         url: "blob:https://example.com/12345678-1234-1234-1234-123456789abc",
         lazy: true,

package/src/core/runtime/runtime.ts

@@ -9,6 +9,8 @@ import { isStaticNotebook } from "../static/static-state";
 import { isWasm } from "../wasm/utils";
 import type { RuntimeConfig } from "./types";
 
+const knownQueryParams = new Set(Object.values(KnownQueryParams));
+
 export class RuntimeManager {
   private initialHealthyCheck = new Deferred<void>();
   private config: RuntimeConfig;
@@ -71,10 +73,7 @@ export class RuntimeManager {
     }
 
     for (const [key, value] of currentParams.entries()) {
-      if (
-        restrictToKnownQueryParams &&
-        !Object.values(KnownQueryParams).includes(key)
-      ) {
+      if (restrictToKnownQueryParams && !knownQueryParams.has(key)) {
         continue;
       }
       baseUrl.searchParams.set(key, value);
@@ -154,7 +153,8 @@ export class RuntimeManager {
    * The WebSocket URL of the runtime.
    */
   public getWsURL(sessionId: SessionId): URL {
-    return this.formatWsURL("/ws", this.getSessionSearchParams(sessionId));
+    const searchParams = this.getSessionSearchParams(sessionId);
+    return this.formatWsURL("/ws", searchParams);
   }
 
   /**

package/src/core/static/files.ts

@@ -125,6 +125,8 @@ function withoutLeadingDot(path: string): string {
 /**
  * Resolve a URL to a blob URL if it's a virtual file, for use with dynamic import().
  * Unlike fetch, import() can't be patched, so we need to convert data URLs to blob URLs.
+ * The caller owns a returned URL that differs from the input and must revoke it
+ * once no module consumers or their cleanup callbacks need it.
  *
  * @returns The original URL if not a virtual file, or a blob URL if it is
  */