@marimo-team/islands 0.25.3-dev15 → 0.25.3-dev151

package/src/core/wasm/worker/worker.ts

@@ -1,5 +1,6 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
+import type { unstable_NotebookCall } from "@marimo-team/client";
 import type { PyodideInterface } from "pyodide";
 import {
   createRPC,
@@ -8,14 +9,12 @@ import {
   type RPCSchema,
 } from "rpc-anywhere";
 import type { UserConfig } from "@/core/config/config-schema";
-import type { NotificationPayload } from "@/core/kernel/messages";
 import type {
   ListPackagesResponse,
   PackageOperationResponse,
+  NotebookDocumentTransactionRequest,
   SaveNotebookRequest,
 } from "@/core/network/types";
-import type { JsonString } from "@/utils/json/base64";
-import { once } from "@/utils/once";
 import { decodeUtf8 } from "@/utils/strings";
 import { Deferred } from "../../../utils/Deferred";
 import { prettyError } from "../../../utils/errors";
@@ -27,12 +26,11 @@ import { TRANSPORT_ID } from "./constants";
 import { WasmFileSystem } from "./fs";
 import { getController } from "./getController";
 import { getPyodideVersion } from "./getPyodideVersion";
-import { MessageBuffer } from "./message-buffer";
 import { t } from "./tracer";
 import type {
   BridgePayload,
   RawBridge,
-  SerializedBridge,
+  WasmSession,
   WasmController,
 } from "./types";
 import { shouldLoadDuckDBPackages } from "../utils";
@@ -72,16 +70,66 @@ async function loadPyodideAndPackages() {
   }
 }
 
-const messageBuffer = new MessageBuffer(
-  (message: JsonString<NotificationPayload>) => {
-    rpc.send.kernelMessage({ message });
-  },
-);
-const bridgeReady = new Deferred<SerializedBridge>();
+const sessionReady = new Deferred<WasmSession>();
 let started = false;
 
 // Handle RPC requests
+const notebookSubscriptions = new Map<
+  string,
+  { promise: Promise<void>; cancel(): void }
+>();
+async function getNotebook() {
+  const session = await sessionReady.promise;
+  return session.bridge.notebook;
+}
+
 const requestHandler = createRPCRequestHandler({
+  notebookSubscribe: (request: { id: string; cursor: string | null }) => {
+    let canceled = false;
+    const subscribing = (async () => {
+      const session = await sessionReady.promise;
+      const notebook = session.bridge.notebook;
+      try {
+        await notebook.subscribe(request.id, request.cursor, (event) => {
+          rpc.send.notebookEvent({ id: request.id, event });
+        });
+        if (!canceled) {
+          void session.start().catch((error: unknown) => {
+            rpc.send.initializedError({ error: prettyError(error) });
+          });
+        }
+      } finally {
+        notebook.destroy();
+      }
+    })();
+    notebookSubscriptions.set(request.id, {
+      promise: subscribing,
+      cancel: () => {
+        canceled = true;
+      },
+    });
+    return subscribing.finally(() => notebookSubscriptions.delete(request.id));
+  },
+  notebookUnsubscribe: async (id: string) => {
+    // An RPC timeout can close a reader while its subscription is still opening.
+    const pending = notebookSubscriptions.get(id);
+    pending?.cancel();
+    await pending?.promise.catch(() => undefined);
+    const notebook = await getNotebook();
+    try {
+      notebook.unsubscribe(id);
+    } finally {
+      notebook.destroy();
+    }
+  },
+  notebookCall: async (call: unstable_NotebookCall): Promise<unknown> => {
+    const notebook = await getNotebook();
+    try {
+      return JSON.parse(await notebook.call(JSON.stringify(call)));
+    } finally {
+      notebook.destroy();
+    }
+  },
   /**
    * Start the session
    */
@@ -105,29 +153,34 @@ const requestHandler = createRPCRequestHandler({
         code: opts.code,
         filename: opts.filename,
       });
-      const startSession = t.wrapAsync(
-        self.controller.startSession.bind(self.controller),
+      const prepareSession = t.wrapAsync(
+        self.controller.prepareSession.bind(self.controller),
       );
-      const initializeOnce = once(() => {
-        rpc.send.initializingMessage({
-          message: "Initializing notebook...",
-        });
-        rpc.send.initialized({});
-      });
       rpc.send.initializingMessage({
         message: "Loading notebook and dependencies...",
       });
-      const bridge = await startSession({
+      const session = await prepareSession({
         code: opts.code,
         filename: opts.filename,
         queryParameters: opts.queryParameters,
         userConfig: opts.userConfig,
-        onMessage: (msg) => {
-          initializeOnce();
-          messageBuffer.push(msg);
-        },
       });
-      bridgeReady.resolve(bridge);
+      const notebook = session.bridge.notebook;
+      try {
+        notebook.set_persistence(async (contents, filename) => {
+          // Keep file operations in the execution worker from syncing stale source.
+          self.pyodide.FS.writeFile(filename, contents);
+          self.pyodide.FS.writeFile(WasmFileSystem.NOTEBOOK_FILENAME, contents);
+          await rpc.proxy.request.persistNotebook({ filename, contents });
+        });
+      } finally {
+        notebook.destroy();
+      }
+      sessionReady.resolve(session);
+      rpc.send.initializingMessage({
+        message: "Initializing notebook...",
+      });
+      rpc.send.initialized({});
       workerInitSpan.end("ok");
     } catch (error) {
       rpc.send.initializedError({
@@ -249,13 +302,21 @@ const requestHandler = createRPCRequestHandler({
     };
   },
 
-  /**
-   * Save the notebook
-   */
-  saveNotebook: async (opts: SaveNotebookRequest) => {
-    await pyodideReadyPromise; // Make sure loading is done
-    const bridge = await bridgeReady.promise;
-    await bridge.save(JSON.stringify(opts));
+  documentTransaction: async (request: NotebookDocumentTransactionRequest) => {
+    const notebook = await getNotebook();
+    try {
+      await notebook.transaction(JSON.stringify(request));
+    } finally {
+      notebook.destroy();
+    }
+  },
+  setNotebookLayout: async (layout: SaveNotebookRequest["layout"]) => {
+    const notebook = await getNotebook();
+    try {
+      await notebook.set_layout(JSON.stringify(layout));
+    } finally {
+      notebook.destroy();
+    }
   },
 
   /**
@@ -302,7 +363,7 @@ const requestHandler = createRPCRequestHandler({
     }
 
     // Perform the function call to the Python bridge
-    const bridge = await bridgeReady.promise;
+    const { bridge } = await sessionReady.promise;
 
     // Serialize the payload
     const payloadString =
@@ -335,10 +396,9 @@ const requestHandler = createRPCRequestHandler({
 export type WorkerSchema = RPCSchema<
   {
     messages: {
+      notebookEvent: { id: string; event: string };
       // Emitted when the worker is ready
       ready: {};
-      // Emitted when the kernel sends a message
-      kernelMessage: { message: JsonString<NotificationPayload> };
       // Emitted when the Pyodide is initialized
       initialized: {};
       // Emitted when the Pyodide is initializing, with new messages
@@ -355,22 +415,15 @@ const rpc = createRPC<WorkerSchema, ParentSchema>({
     transportId: TRANSPORT_ID,
   }),
   requestHandler,
+  // Persistence can include bootstrapping the storage worker.
+  maxRequestTime: Infinity,
 });
 
 rpc.addMessageListener("bootstrap", (config) => runtimeConfig.resolve(config));
 
 rpc.send("ready", {});
 
-/// Listeners
-// When the consumer is ready, start the message buffer
-rpc.addMessageListener("consumerReady", async () => {
-  await pyodideReadyPromise; // Make sure loading is done
-  messageBuffer.start();
-});
-
 const namesThatRequireSync = new Set<keyof RawBridge>([
-  "save",
-  "save_app_config",
   "rename_file",
   "create_file_or_directory",
   "delete_file_or_directory",

package/src/css/globals.css

@@ -75,6 +75,9 @@
     --ring: hsl(215deg 20.2% 65.1%);
 
     /* Semantic colors. */
+    --brand: light-dark(#365f43, #a8c9ae);
+    --brand-hover: light-dark(#2b5037, #bdd8c2);
+    --brand-foreground: light-dark(#fff, #172b1c);
     --destructive: var(--red-9, #e5484d);
     --destructive-hover: var(--red-10, #dc3e42);
     --destructive-border: var(--red-11, #ce2c31);
@@ -89,6 +92,7 @@
     --action-hover: var(--yellow-10, #ffdc00);
     --action-border: var(--yellow-11, #9e6c00);
     --action-foreground: var(--yellow-12, #473b1f);
+    --search-highlight: var(--yellow-4, #fff394);
     --link: light-dark(hsl(211deg 90% 42%), hsl(211deg 90% 62%));
     --link-visited: light-dark(hsl(272deg 51% 54%), hsl(272deg 51% 74%));
     --stale: hsl(42deg 56% 44% / 25%);
@@ -137,6 +141,7 @@
     --action-hover: var(--yellow-7, #665417);
     --action-border: var(--yellow-11, #f5e147);
     --action-foreground: var(--yellow-12, #f6eeb4);
+    --search-highlight: var(--yellow-6, #524202);
     --stale: hsl(54deg 100% 86.7% / 25%);
   }
 }

package/src/hooks/__tests__/useAsyncData.test.tsx

@@ -0,0 +1,148 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { act, render, renderHook, waitFor } from "@testing-library/react";
+import { Activity } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { Deferred } from "@/utils/Deferred";
+import { useAsyncData } from "../useAsyncData";
+
+function AsyncDataStatus({ fetch }: { fetch: () => Promise<string> }) {
+  const result = useAsyncData(fetch, []);
+  return (
+    <output
+      data-status={result.status}
+      data-fetching={result.isFetching}
+      data-error={result.error?.message ?? ""}
+    >
+      {result.data}
+    </output>
+  );
+}
+
+describe("useAsyncData", () => {
+  it.each(["success", "error"] as const)(
+    "restarts fetching when Activity reopens after %s",
+    async (initialStatus) => {
+      const initial = new Deferred<string>();
+      const restarted = new Deferred<string>();
+      const fetch = vi
+        .fn(() => restarted.promise)
+        .mockImplementationOnce(() => initial.promise);
+      const view = render(
+        <Activity mode="visible">
+          <AsyncDataStatus fetch={fetch} />
+        </Activity>,
+      );
+      await act(async () => {
+        if (initialStatus === "success") {
+          initial.resolve("first");
+        } else {
+          initial.reject(new Error("offline"));
+        }
+      });
+      expect(view.getByRole("status").dataset.status).toBe(initialStatus);
+
+      view.rerender(
+        <Activity mode="hidden">
+          <AsyncDataStatus fetch={fetch} />
+        </Activity>,
+      );
+      view.rerender(
+        <Activity mode="visible">
+          <AsyncDataStatus fetch={fetch} />
+        </Activity>,
+      );
+
+      expect(fetch).toHaveBeenCalledTimes(2);
+      expect(view.getByRole("status").dataset).toMatchObject({
+        status: initialStatus === "success" ? "loading" : "pending",
+        error: "",
+        fetching: "true",
+      });
+      expect(view.getByRole("status").textContent).toBe(
+        initialStatus === "success" ? "first" : "",
+      );
+      await act(async () => restarted.resolve("latest"));
+      expect(view.getByRole("status").dataset).toMatchObject({
+        status: "success",
+        fetching: "false",
+      });
+      expect(view.getByRole("status").textContent).toBe("latest");
+    },
+  );
+
+  it("ignores a request canceled when Activity hides", async () => {
+    const canceled = new Deferred<string>();
+    const restarted = new Deferred<string>();
+    const fetch = vi
+      .fn(() => restarted.promise)
+      .mockImplementationOnce(() => canceled.promise);
+    const view = render(
+      <Activity mode="visible">
+        <AsyncDataStatus fetch={fetch} />
+      </Activity>,
+    );
+    view.rerender(
+      <Activity mode="hidden">
+        <AsyncDataStatus fetch={fetch} />
+      </Activity>,
+    );
+    view.rerender(
+      <Activity mode="visible">
+        <AsyncDataStatus fetch={fetch} />
+      </Activity>,
+    );
+    expect(fetch).toHaveBeenCalledTimes(2);
+    await act(async () => canceled.resolve("obsolete"));
+    expect(view.getByRole("status").dataset.status).toBe("pending");
+    expect(view.getByRole("status").textContent).toBe("");
+    await act(async () => restarted.resolve("latest"));
+    expect(view.getByRole("status").dataset.status).toBe("success");
+    expect(view.getByRole("status").textContent).toBe("latest");
+  });
+
+  it("preserves data while refetching and ignores obsolete requests", async () => {
+    const requests = [
+      new Deferred<string>(),
+      new Deferred<string>(),
+      new Deferred<string>(),
+    ];
+    const fetch = vi
+      .fn(() => requests[0].promise)
+      .mockImplementationOnce(() => requests[0].promise)
+      .mockImplementationOnce(() => requests[1].promise)
+      .mockImplementationOnce(() => requests[2].promise);
+    const { result, rerender } = renderHook(
+      ({ key }) => useAsyncData(fetch, [key]),
+      { initialProps: { key: 0 } },
+    );
+    expect(result.current.status).toBe("pending");
+    await act(async () => requests[0].resolve("first"));
+    expect(result.current.data).toBe("first");
+    rerender({ key: 1 });
+    expect(result.current).toMatchObject({ status: "loading", data: "first" });
+    rerender({ key: 2 });
+    await act(async () => requests[1].resolve("obsolete"));
+    expect(result.current).toMatchObject({ status: "loading", data: "first" });
+    await act(async () => requests[2].resolve("latest"));
+    expect(result.current).toMatchObject({ status: "success", data: "latest" });
+  });
+
+  it("retries after errors and allows manual updates during a request", async () => {
+    const request = new Deferred<string>();
+    const fetch = vi
+      .fn<() => Promise<string>>()
+      .mockRejectedValueOnce(new Error("offline"))
+      .mockImplementation(() => request.promise);
+    const { result } = renderHook(() => useAsyncData(fetch, []));
+    await waitFor(() => expect(result.current.status).toBe("error"));
+    act(() => result.current.refetch());
+    expect(result.current.status).toBe("pending");
+    act(() => result.current.setData("manual"));
+    expect(result.current).toMatchObject({ status: "success", data: "manual" });
+    await act(async () => request.resolve("response"));
+    expect(result.current).toMatchObject({
+      status: "success",
+      data: "response",
+    });
+  });
+});

package/src/hooks/__tests__/useDebounce.test.tsx

@@ -121,6 +121,57 @@ describe("useDebounceControlledState", () => {
 
     expect(onChange).not.toHaveBeenCalled();
   });
+
+  it("replaces an uncommitted draft when the external value changes", () => {
+    const onChange = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ value }) =>
+        useDebounceControlledState({
+          initialValue: value,
+          onChange,
+          delay: 1000,
+        }),
+      { initialProps: { value: "initial" } },
+    );
+
+    act(() => result.current.onChange("draft"));
+    rerender({ value: "external" });
+    expect(result.current.value).toBe("external");
+    act(() => vi.runAllTimers());
+    expect(result.current.debouncedValue).toBe("external");
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("handles NaN external values without repeatedly resetting the draft", () => {
+    const onChange = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ value }) =>
+        useDebounceControlledState({ initialValue: value, onChange }),
+      { initialProps: { value: Number.NaN } },
+    );
+
+    expect(result.current.value).toBeNaN();
+    act(() => result.current.onChange(1));
+    rerender({ value: Number.NaN });
+    expect(result.current.value).toBe(1);
+    rerender({ value: 2 });
+    expect(result.current.value).toBe(2);
+    rerender({ value: Number.NaN });
+    expect(result.current.value).toBeNaN();
+  });
+
+  it("resets the draft when the external value changes from zero to negative zero", () => {
+    const onChange = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ value }) =>
+        useDebounceControlledState({ initialValue: value, onChange }),
+      { initialProps: { value: 0 } },
+    );
+
+    act(() => result.current.onChange(1));
+    rerender({ value: -0 });
+    expect(result.current.value).toBe(-0);
+  });
 });
 
 describe("useDebouncedCallback", () => {

package/src/hooks/__tests__/useDeepCompareMemoize.test.tsx

@@ -0,0 +1,39 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { renderHook } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { useDeepCompareMemoize } from "../useDeepCompareMemoize";
+
+describe("useDeepCompareMemoize", () => {
+  it("keeps equal values stable and updates changed values immediately", () => {
+    const initial = { nested: [1, 2] };
+    const { result, rerender } = renderHook(
+      ({ value }) => useDeepCompareMemoize(value),
+      {
+        initialProps: { value: initial },
+      },
+    );
+    rerender({ value: { nested: [1, 2] } });
+    expect(result.current).toBe(initial);
+    const changed = { nested: [1, 3] };
+    rerender({ value: changed });
+    expect(result.current).toBe(changed);
+    rerender({ value: { nested: [1, 3] } });
+    expect(result.current).toBe(changed);
+  });
+
+  it("handles inline callbacks without causing additional renders", () => {
+    let renders = 0;
+    const { result, rerender } = renderHook(
+      ({ value }) => {
+        renders++;
+        return useDeepCompareMemoize({ callback: () => value });
+      },
+      { initialProps: { value: "initial" } },
+    );
+
+    const initialRenders = renders;
+    rerender({ value: "changed" });
+    expect(result.current.callback()).toBe("changed");
+    expect(renders).toBe(initialRenders + 1);
+  });
+});

package/src/hooks/__tests__/useDelayElapsed.test.tsx

@@ -52,4 +52,32 @@ describe("useDelayElapsed", () => {
     // The pending timeout must be cleared, not left dangling.
     expect(vi.getTimerCount()).toBe(0);
   });
+
+  it("handles a NaN delay without resetting on every render", () => {
+    const { result, rerender } = renderHook(() => useDelayElapsed(Number.NaN));
+    expect(result.current).toBe(false);
+
+    act(() => vi.runAllTimers());
+    expect(result.current).toBe(true);
+    rerender();
+    expect(result.current).toBe(true);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("restarts a completed delay after the gate is temporarily disabled", () => {
+    const { result, rerender } = renderHook(
+      ({ delay }) => useDelayElapsed(delay),
+      { initialProps: { delay: 1000 } },
+    );
+    act(() => vi.advanceTimersByTime(1000));
+    expect(result.current).toBe(true);
+    rerender({ delay: 0 });
+    expect(result.current).toBe(true);
+    rerender({ delay: 1000 });
+    expect(result.current).toBe(false);
+    act(() => vi.advanceTimersByTime(999));
+    expect(result.current).toBe(false);
+    act(() => vi.advanceTimersByTime(1));
+    expect(result.current).toBe(true);
+  });
 });

package/src/hooks/__tests__/useInternalStateWithSync.test.tsx

@@ -32,6 +32,26 @@ describe("useInternalStateWithSync", () => {
     expect(result.current[0]).toBe("new value");
   });
 
+  it("preserves function values without calling them and resets when they change", () => {
+    const initial = vi.fn(() => "initial");
+    const draft = vi.fn(() => "draft");
+    const changed = vi.fn(() => "changed");
+    const { result, rerender } = renderHook(
+      ({ value }) => useInternalStateWithSync(value),
+      { initialProps: { value: initial } },
+    );
+
+    expect(result.current[0]).toBe(initial);
+    act(() => result.current[1](() => draft));
+    rerender({ value: initial });
+    expect(result.current[0]).toBe(draft);
+    rerender({ value: changed });
+    expect(result.current[0]).toBe(changed);
+    expect(initial).not.toHaveBeenCalled();
+    expect(draft).not.toHaveBeenCalled();
+    expect(changed).not.toHaveBeenCalled();
+  });
+
   it("should not update internal state if initial value remains the same", () => {
     const { result, rerender } = renderHook(
       ({ value }) => useInternalStateWithSync(value),

package/src/hooks/__tests__/useScript.test.tsx

@@ -0,0 +1,77 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { useScript } from "../useScript";
+
+afterEach(() => {
+  document.querySelectorAll("script").forEach((script) => script.remove());
+});
+
+describe("useScript", () => {
+  it("observes loading and completion of a new script", async () => {
+    const { result } = renderHook(() => useScript("/first.js"));
+    expect(result.current).toBe("loading");
+    await act(async () => {
+      document.querySelector("script")?.dispatchEvent(new Event("load"));
+    });
+    expect(result.current).toBe("ready");
+  });
+
+  it("uses the new source's status when the source changes", async () => {
+    const { result, rerender } = renderHook(({ src }) => useScript(src), {
+      initialProps: { src: "/first.js" },
+    });
+    await act(async () => {
+      document.querySelector("script")?.dispatchEvent(new Event("load"));
+    });
+    expect(result.current).toBe("ready");
+    rerender({ src: "/second.js" });
+    expect(result.current).toBe("loading");
+    await act(async () => {
+      document
+        .querySelector('script[src="/second.js"]')
+        ?.dispatchEvent(new Event("error"));
+    });
+    expect(result.current).toBe("error");
+  });
+
+  it("shares an existing script and only removes scripts it owns", async () => {
+    const owner = renderHook(() =>
+      useScript("/first.js", { removeOnUnmount: true }),
+    );
+    const subscriber = renderHook(() =>
+      useScript("/first.js", { removeOnUnmount: true }),
+    );
+    expect(document.querySelectorAll("script")).toHaveLength(1);
+    await act(async () => {
+      document.querySelector("script")?.dispatchEvent(new Event("load"));
+    });
+    expect(subscriber.result.current).toBe("ready");
+    subscriber.unmount();
+    expect(document.querySelectorAll("script")).toHaveLength(1);
+    owner.unmount();
+    expect(document.querySelectorAll("script")).toHaveLength(0);
+  });
+
+  it("settles for remaining subscribers when the first unmounts mid-load", async () => {
+    const first = renderHook(() => useScript("/shared.js"));
+    const second = renderHook(() => useScript("/shared.js"));
+    first.unmount();
+    expect(second.result.current).toBe("loading");
+    await act(async () => {
+      document.querySelector("script")?.dispatchEvent(new Event("load"));
+    });
+    expect(second.result.current).toBe("ready");
+    // A later subscriber sees the settled status
+    expect(renderHook(() => useScript("/shared.js")).result.current).toBe(
+      "ready",
+    );
+  });
+
+  it("handles sources that are not valid inside a CSS selector", () => {
+    const src = '/odd"name].js';
+    const { result } = renderHook(() => useScript(src));
+    expect(result.current).toBe("loading");
+    expect(document.querySelector("script")?.getAttribute("src")).toBe(src);
+  });
+});