@marimo-team/islands 0.25.3-dev30 → 0.25.3-dev302

package/src/core/transports/server.ts

@@ -0,0 +1,152 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import {
+  type NotebookTransport,
+  sse,
+  StreamStopped,
+  type StreamUrl,
+} from "@marimo-team/client";
+import { jsonParseWithSpecialChar } from "@/utils/json/json-parser";
+import { classifyCloseEvent } from "./connection-state";
+
+/** The server can be slow to accept when many notebooks are open. */
+const CONNECT_MS = 10_000;
+
+/**
+ * The error that ends a stream on this close, or none to retry.
+ *
+ * `cause` is the connection status the editor shows.
+ */
+function stopOn(close: { code?: number; reason?: string }) {
+  const decision = classifyCloseEvent(close);
+  if (decision.kind === "retry") {
+    return undefined;
+  }
+  const reason = "reason" in decision.status ? decision.status.reason : "";
+  return new StreamStopped(reason, { cause: decision.status });
+}
+
+/** Read a URL provider, stopping the stream when it gives up. */
+async function resolve(url: StreamUrl): Promise<URL | undefined> {
+  try {
+    return new URL(typeof url === "function" ? await url() : url);
+  } catch (error) {
+    if (error instanceof StreamStopped) {
+      throw error;
+    }
+    return undefined;
+  }
+}
+
+/** Send each request with the runtime's headers, read before each request. */
+export function withHeaders(
+  headers: () => Record<string, string>,
+): typeof globalThis.fetch {
+  return (input, init) => {
+    const sent = new Headers(init?.headers);
+    for (const [name, value] of Object.entries(headers())) {
+      sent.set(name, value);
+    }
+    return globalThis.fetch(input, { ...init, headers: sent });
+  };
+}
+
+/** A resume cursor and replica belong to the session that produced them. */
+function withSessionIdentity(
+  url: StreamUrl,
+  connect: (target: URL) => NotebookTransport,
+): NotebookTransport {
+  let previous: string | undefined;
+  return async (attempt, handlers) => {
+    const target = await resolve(url);
+    if (target === undefined || attempt.signal.aborted) {
+      return;
+    }
+    target.searchParams.delete("cursor");
+    const identity = new URL(target);
+    identity.searchParams.delete("access_token");
+    identity.searchParams.sort();
+    identity.hash = "";
+    const key = identity.toString();
+    let { cursor } = attempt;
+    if (previous !== undefined && previous !== key) {
+      // Reset both the stream's cursor and its subscribers' state.
+      handlers.message({ event: "reset", data: {} });
+      cursor = null;
+    }
+    previous = key;
+    if (!attempt.signal.aborted) {
+      return connect(target)({ ...attempt, cursor }, handlers);
+    }
+  };
+}
+
+/**
+ * Follow a marimo session over its WebSocket route.
+ *
+ * Each attempt opens one socket with the cursor as a query parameter. The
+ * editor's close policy decides which closes end the stream.
+ *
+ * TODO: Notice a connection that died without closing, such as after a laptop
+ * sleeps. `/sse` sends a heartbeat that its silence limit relies on, and
+ * `/ws` drops it. Sending it on `/ws` would let this transport close a
+ * silent socket.
+ */
+export function websocket(url: StreamUrl): NotebookTransport {
+  return withSessionIdentity(
+    url,
+    (target) =>
+      async ({ cursor, signal }, { open, message }) => {
+        if (cursor !== null) {
+          target.searchParams.set("cursor", cursor);
+        }
+        await new Promise<void>((settle, reject) => {
+          const socket = new WebSocket(target);
+          const timeout = setTimeout(() => socket.close(), CONNECT_MS);
+          const abort = () => socket.close();
+          signal.addEventListener("abort", abort, { once: true });
+          socket.addEventListener("open", () => {
+            clearTimeout(timeout);
+            open();
+          });
+          socket.addEventListener("message", ({ data }) =>
+            // marimo's parser reads `NaN`. A message it cannot read arrives as an
+            // empty object, which `NotebookEvents` rejects as not an event.
+            message(jsonParseWithSpecialChar(String(data))),
+          );
+          socket.addEventListener("close", (event) => {
+            clearTimeout(timeout);
+            signal.removeEventListener("abort", abort);
+            const stopped = signal.aborted ? undefined : stopOn(event);
+            if (stopped === undefined) {
+              settle();
+            } else {
+              reject(stopped);
+            }
+          });
+        });
+      },
+  );
+}
+
+/**
+ * Follow a marimo session over its server-sent events route.
+ *
+ * The session's `close` frames carry the same reasons as WebSocket closes.
+ * marimo's parser decodes tagged bigints and non-finite numbers in every frame.
+ */
+export function sessionSse(
+  url: StreamUrl,
+  headers: () => Record<string, string>,
+): NotebookTransport {
+  return withSessionIdentity(url, (target) =>
+    sse(target, {
+      parseData: jsonParseWithSpecialChar,
+      fetch: withHeaders(headers),
+      stop: (frame) =>
+        frame.event === "close"
+          ? stopOn(frame.data as { code?: number; reason?: string })
+          : undefined,
+    }),
+  );
+}

package/src/core/transports/static.ts

@@ -0,0 +1,173 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/** A backend that serves a document snapshot without a host. */
+
+import type { NotebookClient } from "@marimo-team/client";
+import type * as Protocol from "@marimo-team/client/protocol";
+import type { NotebookBackend } from "../notebook/replica";
+
+/** A document snapshot with its own identity and revision metadata. */
+export interface StaticNotebookSnapshot {
+  readonly notebook: Omit<Protocol.Notebook, "operations">;
+  readonly document: Protocol.Document;
+  readonly cells: readonly Protocol.Cell[];
+  /** What the cells last produced, as completed executions. */
+  readonly results: readonly Protocol.Execution[];
+}
+
+/** The events that describe a snapshot, in the order a host sends them. */
+function snapshotFrames(snapshot: StaticNotebookSnapshot): Protocol.Event[] {
+  return [
+    {
+      event: "notebook",
+      data: { notebook: { ...snapshot.notebook, operations: [] } },
+    },
+    ...snapshot.cells.map((cell): Protocol.CellEvent => ({
+      event: "cell",
+      data: { cell },
+    })),
+    { event: "document", data: { document: snapshot.document } },
+    ...snapshot.results.map((execution): Protocol.ExecutionEvent => ({
+      event: "execution",
+      data: { execution },
+    })),
+  ];
+}
+
+/** A snapshot of a notebook with no cells. */
+export function emptySnapshot(notebookId: string): StaticNotebookSnapshot {
+  return {
+    notebook: {
+      id: notebookId,
+      project_id: notebookId,
+      path: null,
+      name: "",
+      updated_at: null,
+    },
+    document: {
+      notebook_id: notebookId,
+      order: [],
+      app_config: {},
+      etag: `${notebookId}:document`,
+      saved_etag: `${notebookId}:document`,
+      order_etag: `${notebookId}:order`,
+      app_config_etag: `${notebookId}:app_config`,
+      version: 1,
+    },
+    cells: [],
+    results: [],
+  };
+}
+
+/**
+ * Show a snapshot until `live` answers.
+ *
+ * The page carries the notebook it was served with, so cells appear before
+ * the host connects. The snapshot ends in a `ready` of its own, like a
+ * static notebook's, so the replica publishes it. At the host's first sign
+ * of life a `reset` discards it, and the host's snapshot takes over. A
+ * connection that resumes from a host cursor skips the snapshot; one that
+ * resumes from the snapshot's cursor starts the host connection fresh,
+ * since the host never issued it.
+ */
+export function startWithSnapshot(
+  snapshot: StaticNotebookSnapshot,
+  live: NotebookBackend,
+): NotebookBackend {
+  const cursor = `${snapshot.notebook.id}:snapshot`;
+  return {
+    ...live,
+    transport: (attempt, handlers) => {
+      if (attempt.cursor !== null && attempt.cursor !== cursor) {
+        return live.transport(attempt, handlers);
+      }
+      if (attempt.cursor === null) {
+        for (const frame of snapshotFrames(snapshot)) {
+          if (attempt.signal.aborted) {
+            break;
+          }
+          handlers.message(frame);
+        }
+        if (attempt.signal.aborted) {
+          return Promise.resolve();
+        }
+        handlers.message({ event: "ready", id: cursor, data: {} });
+      }
+      let shown = true;
+      const discard = () => {
+        if (shown) {
+          shown = false;
+          handlers.message({ event: "reset", data: {} });
+        }
+      };
+      return live.transport(
+        { ...attempt, cursor: null },
+        {
+          open: () => {
+            discard();
+            handlers.open();
+          },
+          message: (frame) => {
+            discard();
+            handlers.message(frame);
+          },
+        },
+      );
+    },
+  };
+}
+
+/**
+ * Serve a document without a server, runtime, or mutation operations.
+ * Callers and readers must treat the snapshot records as immutable.
+ */
+export function createStaticNotebookBackend(
+  snapshot: StaticNotebookSnapshot,
+): NotebookBackend {
+  const frames: Protocol.Event[] = [
+    ...snapshotFrames(snapshot),
+    { event: "ready", id: "static", data: {} },
+  ];
+
+  return {
+    transport: ({ cursor, signal }, { open, message }) =>
+      new Promise((resolve) => {
+        if (signal.aborted) {
+          resolve();
+          return;
+        }
+        // Finishing would ask NotebookEvents to reconnect. A snapshot stays open
+        // until its reader closes, even though there are no more updates.
+        signal.addEventListener("abort", () => resolve(), { once: true });
+        open();
+        if (cursor !== null && !signal.aborted) {
+          message({ event: "reset", data: {} });
+        }
+        for (const frame of frames) {
+          if (signal.aborted) {
+            return;
+          }
+          message(frame);
+        }
+      }),
+    notebook: () => {
+      const unsupported: NotebookClient["save"] = async (options) => {
+        options?.signal?.throwIfAborted();
+        return {
+          ok: false,
+          status: 501,
+          problem: {
+            type: "tag:marimo.io,2026:host/unsupported-operation",
+            title: "Unsupported operation",
+            status: 501,
+            detail: "Static notebooks do not support mutations",
+          },
+        };
+      };
+      return {
+        edit: (_changes, options) => unsupported(options),
+        save: unsupported,
+      };
+    },
+  };
+}

package/src/core/transports/wasm.ts

@@ -0,0 +1,97 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/** A backend for the notebook running in the WASM worker. */
+
+import {
+  NotebookClient,
+  StreamStopped,
+  type unstable_NotebookCall,
+} from "@marimo-team/client";
+import type { NotebookBackend } from "../notebook/replica";
+
+/** The worker owns the notebook; this interface only carries commands and events. */
+export interface WasmNotebookBridge {
+  subscribe(
+    cursor: string | null,
+    emit: (event: unknown) => void,
+    signal: AbortSignal,
+  ): Promise<() => void>;
+  /** Deliver a call to the worker and resolve with its status and body. */
+  call(call: unstable_NotebookCall): Promise<unknown>;
+}
+
+/** Stop waiting on cancellation; a command already sent may still commit. */
+function abortable<T>(
+  send: () => Promise<T>,
+  signal?: AbortSignal,
+): Promise<T> {
+  if (!signal) {
+    return send();
+  }
+  signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason);
+    signal.addEventListener("abort", abort, { once: true });
+    send()
+      .then(resolve, reject)
+      .finally(() => signal.removeEventListener("abort", abort));
+  });
+}
+
+export function createWasmNotebookBackend(
+  bridge: WasmNotebookBridge,
+): NotebookBackend {
+  return {
+    transport: async ({ cursor, signal }, { open, message }) => {
+      if (signal.aborted) {
+        return;
+      }
+      let unsubscribe: (() => void) | undefined;
+      let finish!: () => void;
+      const closed = new Promise<void>((resolve) => {
+        finish = resolve;
+      });
+      const abort = () => {
+        unsubscribe?.();
+        finish();
+      };
+      signal.addEventListener("abort", abort, { once: true });
+      try {
+        open();
+        // Keep the pending subscription so a close during startup still releases it.
+        await abortable(
+          () =>
+            bridge
+              .subscribe(
+                cursor,
+                (event) => {
+                  if (!signal.aborted) {
+                    message(event);
+                  }
+                },
+                signal,
+              )
+              .then((close) => {
+                unsubscribe = close;
+                if (signal.aborted) {
+                  close();
+                }
+              }),
+          signal,
+        );
+        await closed;
+      } catch (error) {
+        if (!signal.aborted) {
+          unsubscribe?.();
+          throw new StreamStopped("Could not follow the WASM notebook", {
+            cause: error,
+          });
+        }
+      } finally {
+        signal.removeEventListener("abort", abort);
+      }
+    },
+    notebook: (notebookId) =>
+      NotebookClient.unstable_over((call) => bridge.call(call), { notebookId }),
+  };
+}

package/src/core/vscode/__tests__/vscode-bindings.test.ts

@@ -0,0 +1,125 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const logger = vi.hoisted(() => ({
+  log: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+}));
+vi.mock("@/utils/Logger", () => ({ Logger: logger }));
+vi.mock("@/core/hotkeys/shortcuts", () => ({ isPlatformMac: () => true }));
+
+describe("VS Code paste messages", () => {
+  const originalUrl = window.location.href;
+  const setData = vi.fn();
+  let parent: Window;
+  let child: Window;
+  let input: HTMLTextAreaElement;
+  let cleanupListeners: () => void;
+  const onPaste = vi.fn();
+
+  beforeEach(async () => {
+    vi.resetModules();
+    const parentFrame = document.createElement("iframe");
+    const childFrame = document.createElement("iframe");
+    input = document.createElement("textarea");
+    document.body.append(parentFrame, childFrame, input);
+    if (!parentFrame.contentWindow || !childFrame.contentWindow) {
+      throw new Error("Test frames need windows");
+    }
+    parent = parentFrame.contentWindow;
+    child = childFrame.contentWindow;
+    vi.stubGlobal("parent", parent);
+    vi.stubGlobal(
+      "DataTransfer",
+      class {
+        public setData = setData;
+      },
+    );
+    vi.stubGlobal(
+      "ClipboardEvent",
+      class extends Event {
+        public clipboardData: DataTransfer | undefined;
+        public constructor(type: string, init: ClipboardEventInit) {
+          super(type);
+          this.clipboardData = init.clipboardData ?? undefined;
+        }
+      },
+    );
+    window.history.replaceState(null, "", "?vscode=true");
+    input.addEventListener("paste", onPaste);
+    input.focus();
+    const windowListeners = vi.spyOn(window, "addEventListener");
+    const documentListeners = vi.spyOn(document, "addEventListener");
+    cleanupListeners = () => {
+      for (const [type, listener, options] of windowListeners.mock.calls) {
+        window.removeEventListener(type, listener, options);
+      }
+      for (const [type, listener, options] of documentListeners.mock.calls) {
+        document.removeEventListener(type, listener, options);
+      }
+    };
+    const { maybeRegisterVSCodeBindings } = await import("../vscode-bindings");
+    maybeRegisterVSCodeBindings();
+  });
+
+  afterEach(() => {
+    cleanupListeners();
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+    document.body.replaceChildren();
+    window.history.replaceState(null, "", originalUrl);
+  });
+
+  function send(data: unknown, source: Window | null = parent) {
+    window.dispatchEvent(
+      new MessageEvent("message", {
+        data,
+        source,
+        origin: "vscode-webview://dynamic-parent",
+      }),
+    );
+  }
+
+  it.each(["clipboard text", ""])(
+    "accepts parent paste with text %j",
+    (text) => {
+      send({ command: "paste", text });
+      expect(setData).toHaveBeenCalledWith("text/plain", text);
+      expect(onPaste).toHaveBeenCalledOnce();
+      expect(logger.error).not.toHaveBeenCalled();
+    },
+  );
+
+  it("rejects a child frame even when its reported origin matches", () => {
+    send({ command: "paste", text: "unsolicited" }, child);
+    expect(onPaste).not.toHaveBeenCalled();
+    expect(setData).not.toHaveBeenCalled();
+  });
+
+  it("rejects a message without a source window", () => {
+    send({ command: "paste", text: "unsolicited" }, null);
+    expect(onPaste).not.toHaveBeenCalled();
+  });
+
+  it.each(
+    [
+      null,
+      [],
+      {},
+      "paste",
+      1,
+      true,
+      { command: "paste" },
+      { command: "paste", text: {} },
+      { command: "paste", text: 12 },
+      { command: "paste", text: null },
+      { command: "execute", text: "unexpected" },
+    ].map((data) => ({ data })),
+  )("ignores malformed parent messages without errors: %j", ({ data }) => {
+    send(data);
+    expect(onPaste).not.toHaveBeenCalled();
+    expect(setData).not.toHaveBeenCalled();
+    expect(logger.error).not.toHaveBeenCalled();
+  });
+});

package/src/core/vscode/vscode-bindings.ts

@@ -1,6 +1,7 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
 import { Logger } from "@/utils/Logger";
+import { isRecord } from "@/utils/records";
 import { KnownQueryParams } from "../constants";
 import { isPlatformMac } from "../hotkeys/shortcuts";
 import { isWasm } from "../wasm/utils";
@@ -53,9 +54,20 @@ function registerCopyPaste() {
     });
   });
 
-  window.addEventListener("message", async (event) => {
+  window.addEventListener("message", async (event: MessageEvent<unknown>) => {
+    // VS Code assigns each parent webview a different origin.
+    if (event.source !== window.parent) {
+      return;
+    }
+    const message = event.data;
+    if (
+      !isRecord(message) ||
+      message.command !== "paste" ||
+      typeof message.text !== "string"
+    ) {
+      return;
+    }
     try {
-      const message = event.data;
       const isMac = isPlatformMac();
       switch (message.command) {
         case "paste":