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

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

@@ -1,47 +0,0 @@
-/* Copyright 2026 Marimo. All rights reserved. */
-
-import type * as Protocol from "../protocol";
-
-/**
- * Events the stream handles itself.
- *
- * They identify the notebook, discard state, or carry a native
- * notification. Resources do not receive them.
- */
-type StreamEventName = "reset" | "notebook" | "notebook.removed" | "marimo";
-
-/** Events a resource may handle. `ready` marks the end of the snapshot. */
-export type ResourceEvent = Exclude<
-  Protocol.EventOutput,
-  { event: StreamEventName }
->;
-
-/** What a handler may know about the stream beyond the event. */
-export interface HandlerContext {
-  /** `snapshot` until `ready` arrives and `live` after it. */
-  readonly phase: "snapshot" | "live";
-}
-
-/**
- * A pure handler for each event the resource reads.
- *
- * A handler returns `state` when the event does not apply to it.
- */
-type EventHandlers<State> = {
-  readonly [Name in ResourceEvent["event"]]?: (
-    state: State,
-    event: Extract<ResourceEvent, { event: Name }>,
-    context: HandlerContext,
-  ) => State;
-};
-
-/**
- * One kind of object assembled from its events.
- *
- * The stream returns a resource to `initial` on `reset` and when the
- * notebook is removed.
- */
-export interface Resource<State> {
-  readonly initial: State;
-  readonly on: EventHandlers<State>;
-}

package/src/core/host/stream.ts

@@ -1,211 +0,0 @@
-/* Copyright 2026 Marimo. All rights reserved. */
-
-import type { NotebookEvent } from "./events";
-import type * as Protocol from "./protocol";
-import type {
-  HandlerContext,
-  Resource,
-  ResourceEvent,
-} from "./resources/resource";
-
-/** A resource for each entry of a state map under the same name. */
-type Resources<States> = {
-  readonly [Name in keyof States]: Resource<States[Name]>;
-};
-
-/**
- * The state of one notebook stream.
- *
- * Holds the phase, the notebook identity, the resume cursor, and the state
- * of each resource.
- */
-interface StreamState<States> {
-  readonly phase: HandlerContext["phase"];
-  /**
-   * The notebook the stream describes.
-   *
-   * Retained across `reset`.
-   */
-  readonly notebookId: Protocol.NotebookIdOutput | null;
-  /**
-   * The id of the last live event.
-   *
-   * Null before `ready` and after `reset`.
-   */
-  readonly cursor: string | null;
-  /** The state of each resource by name. */
-  readonly resources: States;
-}
-
-/** A reducer over the events of one notebook stream. */
-interface Stream<States> {
-  readonly initial: StreamState<States>;
-  /**
-   * Apply one event.
-   *
-   * Throws on a live event without a cursor or on an object from another
-   * notebook.
-   */
-  reduce(state: StreamState<States>, event: NotebookEvent): StreamState<States>;
-  /**
-   * The state to hold while reconnecting.
-   *
-   * A live stream keeps its state and resumes from `cursor`. An incomplete
-   * snapshot starts over.
-   */
-  resume(state: StreamState<States>): StreamState<States>;
-}
-
-/** Events that may arrive without a cursor after `ready`. */
-const UNCURSORED = new Set<NotebookEvent["event"]>([
-  "reset",
-  "marimo",
-  "unknown",
-]);
-
-/**
- * The notebook the event's object belongs to.
- *
- * Undefined for objects that do not name one.
- */
-function notebookIdOf(
-  event: ResourceEvent,
-): Protocol.NotebookIdOutput | undefined {
-  switch (event.event) {
-    case "document":
-      return event.data.document.notebook_id;
-    case "cell":
-      return event.data.cell.notebook_id;
-    case "analysis":
-      return event.data.analysis.notebook_id;
-    case "runtime":
-      return event.data.runtime.notebook_id;
-    case "attachment":
-      return event.data.attachment.notebook_id;
-    case "run":
-      return event.data.run.notebook_id;
-    default:
-      return undefined;
-  }
-}
-
-/** Compose resources into one stream. */
-export function createStream<States extends object>(
-  resources: Resources<States>,
-): Stream<States> {
-  const names = Object.keys(resources) as (keyof States & string)[];
-  const initialResources = Object.fromEntries(
-    names.map((name) => [name, resources[name].initial]),
-  ) as States;
-  const initial: StreamState<States> = {
-    phase: "snapshot",
-    notebookId: null,
-    cursor: null,
-    resources: initialResources,
-  };
-
-  function identify(
-    state: StreamState<States>,
-    notebookId: Protocol.NotebookIdOutput,
-  ): StreamState<States> {
-    if (state.notebookId === notebookId) {
-      return state;
-    }
-    if (state.notebookId !== null) {
-      throw new Error("Notebook stream changed identity");
-    }
-    return { ...state, notebookId };
-  }
-
-  function clear(state: StreamState<States>): StreamState<States> {
-    return state.resources === initialResources
-      ? state
-      : { ...state, resources: initialResources };
-  }
-
-  function fanOut(
-    state: StreamState<States>,
-    event: ResourceEvent,
-  ): StreamState<States> {
-    const context: HandlerContext = { phase: state.phase };
-    let next = state.resources;
-    for (const name of names) {
-      type State = States[typeof name];
-      // Handlers are keyed by the event name they accept.
-      const handler = resources[name].on[event.event] as
-        | ((
-            state: State,
-            event: Protocol.EventOutput,
-            context: HandlerContext,
-          ) => State)
-        | undefined;
-      if (handler === undefined) {
-        continue;
-      }
-      const before = next[name];
-      const after = handler(before, event, context);
-      if (after !== before) {
-        next = { ...next, [name]: after };
-      }
-    }
-    return next === state.resources ? state : { ...state, resources: next };
-  }
-
-  /** Record the position of a live event. */
-  function advance(
-    state: StreamState<States>,
-    id: string | undefined,
-  ): StreamState<States> {
-    return state.phase === "live" && id !== undefined && id !== state.cursor
-      ? { ...state, cursor: id }
-      : state;
-  }
-
-  return {
-    initial,
-    reduce(state, event) {
-      if (
-        state.phase === "live" &&
-        event.id === undefined &&
-        !UNCURSORED.has(event.event)
-      ) {
-        throw new Error("Live notebook event is missing its cursor");
-      }
-      switch (event.event) {
-        case "marimo":
-        case "unknown":
-          return advance(state, event.id);
-        case "reset":
-          return { ...initial, notebookId: state.notebookId };
-        case "ready":
-          // Handlers see the phase that ended, so a snapshot's ready differs
-          // from one that ends a replay.
-          return { ...fanOut(state, event), phase: "live", cursor: event.id };
-        case "notebook":
-          return advance(identify(state, event.data.notebook.id), event.id);
-        case "notebook.removed":
-          return advance(
-            state.notebookId !== null && event.data.id !== state.notebookId
-              ? state
-              : clear(state),
-            event.id,
-          );
-        default: {
-          const notebookId = notebookIdOf(event);
-          return advance(
-            fanOut(
-              notebookId === undefined ? state : identify(state, notebookId),
-              event,
-            ),
-            event.id,
-          );
-        }
-      }
-    },
-    resume(state) {
-      return state.phase === "snapshot"
-        ? { ...initial, notebookId: state.notebookId }
-        : state;
-    },
-  };
-}

package/src/core/rtc/state.ts

@@ -1,34 +0,0 @@
-/* Copyright 2026 Marimo. All rights reserved. */
-import { atomWithStorage } from "jotai/utils";
-import { SCRATCH_CELL_ID, type CellId } from "@/core/cells/ids";
-import { once } from "@/utils/once";
-import { jotaiJsonStorage } from "@/utils/storage/jotai";
-import { getFeatureFlag } from "../config/feature-flag";
-
-/**
- * The username for the current user when using real-time collaboration.
- * This is stored in localStorage.
- */
-export const usernameAtom = atomWithStorage<string>(
-  "marimo:rtc:username",
-  "",
-  jotaiJsonStorage,
-);
-
-/**
- * Whether RTC is enabled.
- *
- * This is cached on page-load because this UI can get into
- * weird states, so we require a page reload to take effect.
- */
-export const isRtcEnabled = once(() => {
-  return getFeatureFlag("rtc_v2");
-});
-
-/**
- * Whether this cell type can participate in real-time collaboration.
- * Scratchpad cells are local-only.
- */
-export function canUseRtc(cellId: CellId): boolean {
-  return cellId !== SCRATCH_CELL_ID;
-}

package/src/core/state/__tests__/jotai.test.ts

@@ -1,25 +0,0 @@
-/* Copyright 2026 Marimo. All rights reserved. */
-
-import { atom } from "jotai";
-import { describe, expect, it } from "vitest";
-import { store, waitFor } from "../jotai";
-
-describe("waitFor function", () => {
-  it("should resolve when the atom satisfies the predicate", async () => {
-    const testAtom = atom(0);
-    store.set(testAtom, 10);
-
-    const result = await waitFor(testAtom, (value) => value === 10);
-    expect(result).toBe(10);
-  });
-
-  it("should resolve when the atom changes to satisfy the predicate", async () => {
-    const testAtom = atom(0);
-
-    setTimeout(() => store.set(testAtom, 15), 5);
-    setTimeout(() => store.set(testAtom, 20), 10);
-
-    const result = await waitFor(testAtom, (value) => value === 20);
-    expect(result).toBe(20);
-  });
-});

package/src/core/wasm/worker/message-buffer.ts

@@ -1,33 +0,0 @@
-/* Copyright 2026 Marimo. All rights reserved. */
-
-/**
- * A buffer for messages that are received before the worker is ready to process them.
- * Once the worker is ready, the buffer is flushed.
- */
-export class MessageBuffer<T> {
-  private buffer: T[];
-  private started = false;
-  private onMessage: (data: T) => void;
-  public constructor(onMessage: (data: T) => void) {
-    this.onMessage = onMessage;
-    this.buffer = [];
-  }
-
-  public push = (data: T) => {
-    if (this.started) {
-      this.onMessage(data);
-    } else {
-      this.buffer.push(data);
-    }
-  };
-
-  /**
-   * Start processing messages
-   */
-  public start = () => {
-    this.started = true;
-    // Flush the buffer
-    this.buffer.forEach((data) => this.onMessage(data));
-    this.buffer = [];
-  };
-}

package/src/core/websocket/__tests__/createConnectionTransport.test.ts

@@ -1,49 +0,0 @@
-/* Copyright 2026 Marimo. All rights reserved. */
-
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { BasicTransport } from "../transports/basic";
-import { SseTransport } from "../transports/sse";
-import { WsTransport } from "../transports/ws";
-import { createConnectionTransport } from "../transports/create";
-
-vi.mock("../../wasm/utils", () => ({
-  isWasm: () => false,
-}));
-
-describe("createConnectionTransport", () => {
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  const options = {
-    url: () => "http://localhost/ws",
-    headers: () => ({}),
-  };
-
-  it("uses BasicTransport for static notebooks", () => {
-    const transport = createConnectionTransport({
-      ...options,
-      static: true,
-      transportType: "websocket",
-    });
-    expect(transport).toBeInstanceOf(BasicTransport);
-  });
-
-  it("uses WsTransport by default", () => {
-    const transport = createConnectionTransport({
-      ...options,
-      static: false,
-      transportType: "websocket",
-    });
-    expect(transport).toBeInstanceOf(WsTransport);
-  });
-
-  it("uses SseTransport when the transport type is sse", () => {
-    const transport = createConnectionTransport({
-      ...options,
-      static: false,
-      transportType: "sse",
-    });
-    expect(transport).toBeInstanceOf(SseTransport);
-  });
-});

package/src/core/websocket/__tests__/useNotebookClient.hook.test.tsx

@@ -1,170 +0,0 @@
-/* Copyright 2026 Marimo. All rights reserved. */
-// @vitest-environment jsdom
-
-import { act, renderHook } from "@testing-library/react";
-import { createStore, Provider } from "jotai";
-import type { PropsWithChildren } from "react";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { ConnectionState } from "../types";
-import { createConnectionTransport } from "../transports/create";
-import type { IConnectionTransport } from "../transports/transport";
-import { useNotebookClient } from "../useNotebookClient";
-import { fixtureMessages } from "../../host/__tests__/fixtures";
-import { agentAttachmentsAtom } from "../../attachments/state";
-import { notebookClientAtom } from "../state";
-
-vi.mock("../transports/create", () => ({ createConnectionTransport: vi.fn() }));
-
-function makeTransport() {
-  const events = new EventTarget();
-  const transport: IConnectionTransport = {
-    readyState: WebSocket.CLOSED,
-    reconnect: vi.fn(() => {
-      transport.readyState = WebSocket.OPEN;
-      events.dispatchEvent(new Event("open"));
-    }),
-    close: vi.fn(() => {
-      transport.readyState = WebSocket.CLOSED;
-      events.dispatchEvent(new CloseEvent("close"));
-    }),
-    send: vi.fn(),
-    addEventListener: events.addEventListener.bind(events),
-    removeEventListener: events.removeEventListener.bind(events),
-  };
-  return {
-    transport,
-    receive: (message: unknown) =>
-      events.dispatchEvent(
-        new MessageEvent("message", { data: JSON.stringify(message) }),
-      ),
-    notify: () =>
-      events.dispatchEvent(
-        new MessageEvent("message", {
-          data: JSON.stringify({
-            event: "marimo",
-            data: { marimo: { op: "reconnected" } },
-          }),
-        }),
-      ),
-  };
-}
-
-function setup(strict = false) {
-  const store = createStore();
-  const options = {
-    sessionId: "first",
-    static: false,
-    transportType: "websocket" as const,
-    messageFormat: "host" as const,
-    url: () => "ws://localhost/ws",
-    headers: () => ({}),
-    waitUntilReady: async () => undefined,
-    checkHealth: async () => true,
-    onNotification: vi.fn(),
-    onMessageError: vi.fn(),
-  };
-  const wrapper = ({ children }: PropsWithChildren) => (
-    <Provider store={store}>{children}</Provider>
-  );
-  const hook = renderHook((props) => useNotebookClient(props), {
-    initialProps: options,
-    reactStrictMode: strict,
-    wrapper,
-  });
-  return { ...hook, options, store };
-}
-
-beforeEach(() => {
-  vi.mocked(createConnectionTransport).mockReset();
-});
-
-describe("useNotebookClient", () => {
-  it("exposes host presence to the UI without waiting for kernel-ready", async () => {
-    const transport = makeTransport();
-    vi.mocked(createConnectionTransport).mockReturnValue(transport.transport);
-    const { result, store, unmount } = setup();
-    await act(async () => Promise.resolve());
-    expect(store.get(notebookClientAtom)).toBe(result.current);
-    act(() =>
-      fixtureMessages("notebook-events.sse").forEach(transport.receive),
-    );
-    expect(store.get(agentAttachmentsAtom)).toEqual([
-      {
-        id: "a2",
-        notebook_id: "n1",
-        kind: "agent",
-        name: "Notebook CLI",
-        since: "2026-10-01T09:20:03Z",
-      },
-    ]);
-    unmount();
-    expect(store.get(notebookClientAtom)).toBeNull();
-    expect(store.get(agentAttachmentsAtom)).toEqual([]);
-  });
-
-  it("uses current callbacks and URL providers without reconnecting on a rerender", async () => {
-    const first = makeTransport();
-    vi.mocked(createConnectionTransport).mockReturnValue(first.transport);
-    const { rerender, options, unmount } = setup();
-    await act(async () => Promise.resolve());
-    const onNotification = vi.fn();
-    rerender({ ...options, onNotification, url: () => "ws://redirected/ws" });
-    act(() => first.notify());
-    expect(options.onNotification).not.toHaveBeenCalled();
-    expect(onNotification).toHaveBeenCalledExactlyOnceWith({
-      data: { op: "reconnected" },
-    });
-    expect(createConnectionTransport).toHaveBeenCalledOnce();
-    expect(vi.mocked(createConnectionTransport).mock.calls[0][0].url()).toBe(
-      "ws://redirected/ws",
-    );
-    unmount();
-  });
-
-  it("replaces the transport when session identity changes and ignores old messages", async () => {
-    const first = makeTransport();
-    const second = makeTransport();
-    vi.mocked(createConnectionTransport)
-      .mockReturnValueOnce(first.transport)
-      .mockReturnValueOnce(second.transport);
-    const { rerender, options, unmount } = setup();
-    await act(async () => Promise.resolve());
-    rerender({ ...options, sessionId: "second" });
-    await act(async () => Promise.resolve());
-    expect(first.transport.close).toHaveBeenCalledOnce();
-    act(() => {
-      first.notify();
-      second.notify();
-    });
-    expect(options.onNotification).toHaveBeenCalledOnce();
-    unmount();
-  });
-
-  it("cleans up every transport under Strict Mode and only connects the active lifetime", async () => {
-    const transports: ReturnType<typeof makeTransport>[] = [];
-    vi.mocked(createConnectionTransport).mockImplementation(() => {
-      const next = makeTransport();
-      transports.push(next);
-      return next.transport;
-    });
-    const { result, store, options, unmount } = setup(true);
-    await act(async () => Promise.resolve());
-    expect(transports).toHaveLength(2);
-    expect(transports[0].transport.reconnect).not.toHaveBeenCalled();
-    expect(transports[0].transport.close).toHaveBeenCalledOnce();
-    expect(transports[1].transport.reconnect).toHaveBeenCalledOnce();
-    expect(store.get(result.current.connectionAtom)).toEqual({
-      state: ConnectionState.OPEN,
-    });
-    act(() => {
-      for (const transport of transports) {
-        transport.notify();
-      }
-    });
-    expect(options.onNotification).toHaveBeenCalledOnce();
-    unmount();
-    expect(transports[1].transport.close).toHaveBeenCalledOnce();
-    await result.current.reconnect();
-    expect(transports[1].transport.reconnect).toHaveBeenCalledOnce();
-  });
-});

package/src/core/websocket/state.ts

@@ -1,7 +0,0 @@
-/* Copyright 2026 Marimo. All rights reserved. */
-
-import { atom } from "jotai";
-import type { NotebookClient } from "../host/notebook-client";
-
-/** The client owned by the mounted notebook session. */
-export const notebookClientAtom = atom<NotebookClient | null>(null);