@marimo-team/islands 0.24.3-dev2 → 0.24.3-dev22

package/src/components/ui/table.tsx

@@ -7,7 +7,7 @@ const Table = React.forwardRef<
   HTMLTableElement,
   React.HTMLAttributes<HTMLTableElement>
 >(({ className, ...props }, ref) => (
-  <div className="w-full overflow-auto scrollbar-thin flex-1 print:overflow-hidden">
+  <div className="w-full overflow-auto overscroll-contain scrollbar-thin flex-1 print:overflow-hidden">
     <table
       ref={ref}
       className={cn("w-full caption-bottom text-sm", className)}

package/src/core/cells/pending-delete-service.ts

@@ -1,7 +1,6 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
 import { useAtomValue, useStore } from "jotai";
-import { useMemo } from "react";
 import {
   useDeleteCellCallback,
   useDeleteManyCellsCallback,
@@ -130,21 +129,18 @@ export function usePendingDeleteService() {
   const { entries } = useAtomValue(pendingDeleteStateAtom);
   const deleteCell = useDeleteCellCallback();
   const deleteManyCells = useDeleteManyCellsCallback();
-  return useMemo(
-    () => ({
-      submit: (cellIds: CellId[]) => {
-        submit({ cellIds, deleteCell, deleteManyCells, store });
-      },
-      clear,
-      get idle() {
-        return entries.size === 0;
-      },
-      get shouldConfirmDelete() {
-        return entries.size > 1;
-      },
-    }),
-    [store, submit, clear, entries, deleteCell, deleteManyCells],
-  );
+  return {
+    submit: (cellIds: CellId[]) => {
+      submit({ cellIds, deleteCell, deleteManyCells, store });
+    },
+    clear,
+    get idle() {
+      return entries.size === 0;
+    },
+    get shouldConfirmDelete() {
+      return entries.size > 1;
+    },
+  };
 }
 
 export function usePendingDelete(cellId: CellId) {

package/src/core/codemirror/language/__tests__/sql.test.ts

@@ -17,6 +17,7 @@ import type {
 import type { DataSourceConnection } from "@/core/datasets/data-source-connections";
 import {
   dataSourceConnectionsAtom,
+  exportedForTesting as dataSourceTesting,
   setLatestEngineSelected,
 } from "@/core/datasets/data-source-connections";
 import { type ConnectionName, DUCKDB_ENGINE } from "@/core/datasets/engines";
@@ -550,8 +551,8 @@ _df = mo.sql(
     const getLatestEngine = () =>
       store.get(dataSourceConnectionsAtom).latestEngineSelected;
 
-    it("should use default engine initially", () => {
-      expect(getLatestEngine()).toBe(DUCKDB_ENGINE);
+    it("should have no selected engine initially", () => {
+      expect(getLatestEngine()).toBeNull();
     });
 
     it("should persist the selected engine", () => {
@@ -622,6 +623,73 @@ _df = mo.sql(
   });
 
   describe("defaultCode", () => {
+    it("should prefer the newest usable connection until an engine is selected", () => {
+      const previousState = store.get(dataSourceConnectionsAtom);
+      const connection: DataSourceConnection = {
+        name: "first_connection" as ConnectionName,
+        source: "sqlite",
+        display_name: "SQLite",
+        dialect: "sqlite",
+        databases: [],
+      };
+      const newestConnection = {
+        ...connection,
+        name: "newest_connection" as ConnectionName,
+      };
+      const icebergConnection = {
+        ...connection,
+        name: "catalog" as ConnectionName,
+        source: "iceberg",
+      };
+      try {
+        store.set(dataSourceConnectionsAtom, {
+          latestEngineSelected: null,
+          connectionsMap: new Map(),
+        });
+        expect(adapter.defaultMetadata.engine).toBe(DUCKDB_ENGINE);
+        expect(adapter.defaultCode).toBe('_df = mo.sql(f"""SELECT * FROM """)');
+
+        store.set(dataSourceConnectionsAtom, {
+          latestEngineSelected: null,
+          connectionsMap: new Map([
+            [connection.name, connection],
+            [newestConnection.name, newestConnection],
+            [icebergConnection.name, icebergConnection],
+            [DUCKDB_ENGINE, { ...connection, name: DUCKDB_ENGINE }],
+          ]),
+        });
+        expect(adapter.defaultMetadata.engine).toBe(newestConnection.name);
+        expect(adapter.defaultCode).toContain("engine=newest_connection");
+        expect(
+          store.get(dataSourceConnectionsAtom).latestEngineSelected,
+        ).toBeNull();
+
+        const refreshConnection = (connection: DataSourceConnection) => {
+          store.set(
+            dataSourceConnectionsAtom,
+            dataSourceTesting.reducer(store.get(dataSourceConnectionsAtom), {
+              type: "addDataSourceConnection",
+              payload: { connections: [connection] },
+            }),
+          );
+        };
+        refreshConnection(connection);
+        expect(adapter.defaultMetadata.engine).toBe(connection.name);
+        expect(adapter.defaultCode).toContain("engine=first_connection");
+
+        setLatestEngineSelected(connection.name);
+        refreshConnection(newestConnection);
+        expect(adapter.defaultCode).toContain("engine=first_connection");
+
+        setLatestEngineSelected(DUCKDB_ENGINE);
+        refreshConnection(connection);
+        expect(adapter.defaultMetadata.engine).toBe(DUCKDB_ENGINE);
+        expect(adapter.defaultCode).toBe('_df = mo.sql(f"""SELECT * FROM """)');
+      } finally {
+        store.set(dataSourceConnectionsAtom, previousState);
+      }
+    });
+
     it("should include engine in defaultCode when selected", () => {
       const engine = "postgres_engine" as ConnectionName;
       setLatestEngineSelected(engine);

package/src/core/codemirror/language/languages/sql/sql.ts

@@ -76,7 +76,22 @@ export interface SQLLanguageAdapterMetadata extends SQLMetadata {
 }
 
 function getLatestEngine(): ConnectionName {
-  return store.get(dataSourceConnectionsAtom).latestEngineSelected;
+  const { latestEngineSelected, connectionsMap } = store.get(
+    dataSourceConnectionsAtom,
+  );
+  if (latestEngineSelected !== null) {
+    return latestEngineSelected;
+  }
+
+  // Map insertion order prefers the most recently discovered connection.
+  const connections = [...connectionsMap.values()].reverse();
+  return (
+    connections.find(
+      (connection) =>
+        !INTERNAL_SQL_ENGINES.has(connection.name) &&
+        connection.source !== "iceberg",
+    )?.name ?? DUCKDB_ENGINE
+  );
 }
 
 /**

package/src/core/codemirror/rtc/extension.ts

@@ -47,7 +47,10 @@ const awarenessLogger = logger.get("awareness").disabled();
 const AWARENESS_PREFIX = "awareness:";
 
 // Utility functions for message handling
-function prefixMessage(token: string, message: Uint8Array): Uint8Array {
+function prefixMessage(
+  token: string,
+  message: Uint8Array,
+): Uint8Array<ArrayBuffer> {
   const tokenBytes = new TextEncoder().encode(token);
   return new Uint8Array([...tokenBytes, ...message]);
 }
@@ -154,7 +157,7 @@ if (isRtcEnabled()) {
 doc.subscribeLocalUpdates((update) => {
   logger.debug("local update, sending to server");
   const ws = getWs();
-  ws.send(update);
+  ws.send(new Uint8Array(update));
 });
 
 // Handle awareness changes

package/src/core/datasets/__tests__/data-source.test.ts

@@ -106,6 +106,7 @@ describe("data source connections", () => {
 
     let newState = addConnection(connections, state);
     expect(newState.connectionsMap.size).toBe(defaultConnSize + 2);
+    newState = { ...newState, latestEngineSelected: connections[0].name };
 
     newState = reducer(newState, {
       type: "removeDataSourceConnection",
@@ -113,6 +114,7 @@ describe("data source connections", () => {
     });
     expect(newState.connectionsMap.size).toBe(defaultConnSize + 1);
     expect(newState.connectionsMap.has("conn2" as ConnectionName)).toBe(true);
+    expect(newState.latestEngineSelected).toBeNull();
   });
 
   it("can clear all connections", () => {

package/src/core/datasets/data-source-connections.ts

@@ -44,7 +44,8 @@ export interface DataSourceConnection extends Omit<
 export type ConnectionsMap = ReadonlyMap<ConnectionName, DataSourceConnection>;
 
 export interface DataSourceState {
-  latestEngineSelected: ConnectionName;
+  // Null permits automatic selection; DuckDB can also be an explicit choice.
+  latestEngineSelected: ConnectionName | null;
   connectionsMap: ConnectionsMap;
 }
 
@@ -110,7 +111,7 @@ function tableSchemaPath(sqlTableContext: SQLTableContext): string[] {
 
 function initialState(): DataSourceState {
   return {
-    latestEngineSelected: DUCKDB_ENGINE,
+    latestEngineSelected: null,
     connectionsMap: initialConnections,
   };
 }
@@ -136,6 +137,8 @@ const {
     // Backend will dedupe by connection name & keep the latest, so we use this as the key
     const newMap = new Map(connectionsMap);
     for (const conn of opts.connections) {
+      // Refresh insertion order so automatic selection follows discovery recency.
+      newMap.delete(conn.name);
       newMap.set(conn.name, conn);
     }
 
@@ -161,16 +164,17 @@ const {
       }),
     );
     return {
-      // If the latest engine selected is not in the new map, use the default engine
-      latestEngineSelected: newMap.has(latestEngineSelected)
-        ? latestEngineSelected
-        : DUCKDB_ENGINE,
+      // Allow automatic selection again when the selected connection disappears.
+      latestEngineSelected:
+        latestEngineSelected && newMap.has(latestEngineSelected)
+          ? latestEngineSelected
+          : null,
       connectionsMap: newMap,
     };
   },
 
   clearDataSourceConnections: (): DataSourceState => ({
-    latestEngineSelected: DUCKDB_ENGINE,
+    latestEngineSelected: null,
     connectionsMap: new Map(),
   }),
 
@@ -183,9 +187,10 @@ const {
     const newMap = new Map(connectionsMap);
     newMap.delete(connectionName);
     return {
-      latestEngineSelected: newMap.has(latestEngineSelected)
-        ? latestEngineSelected
-        : DUCKDB_ENGINE,
+      latestEngineSelected:
+        latestEngineSelected && newMap.has(latestEngineSelected)
+          ? latestEngineSelected
+          : null,
       connectionsMap: newMap,
     };
   },

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

@@ -19,6 +19,13 @@ import {
 } from "../parse";
 import { createMockIslandElement, createMockIslands } from "./test-utils.tsx";
 
+function islandSnapshotPath(filename: string): string {
+  return new URL(
+    `../../../../../tests/_islands/snapshots/${filename}`,
+    import.meta.url,
+  ).pathname.replace(/^\/@fs/, "");
+}
+
 function createPayloadCell(
   overrides: Partial<{
     cellId: string;
@@ -47,6 +54,7 @@ function appendPayload(
   payload: {
     schemaVersion: number;
     appId: string;
+    dependencies?: unknown;
     cells: ReturnType<typeof createPayloadCell>[];
   },
 ) {
@@ -58,6 +66,33 @@ function appendPayload(
 }
 
 describe("createMarimoFile", () => {
+  it("should serialize dependencies as top-level script metadata", () => {
+    const file = createMarimoFile({
+      dependencies: ['cowsay==6.1; sys_platform == "emscripten"'],
+      cells: [{ code: "import cowsay" }],
+    });
+    expect(file).toBe(
+      [
+        "# /// script",
+        '# dependencies = ["cowsay==6.1; sys_platform == \\"emscripten\\""]',
+        "# ///",
+        "import marimo",
+        "app = marimo.App()",
+        "@app.cell",
+        "def __():",
+        "    import cowsay",
+        "    return",
+      ].join("\n"),
+    );
+  });
+
+  it("should omit metadata for empty dependencies", () => {
+    const cells = [{ code: "import cowsay" }];
+    expect(createMarimoFile({ cells, dependencies: [] })).toBe(
+      createMarimoFile({ cells }),
+    );
+  });
+
   it("should return a string", () => {
     const app = {
       cells: [
@@ -736,13 +771,7 @@ describe("parseMarimoIslandApps", () => {
   });
 
   it("should parse Python-generated island payload snapshots", () => {
-    const html = readFileSync(
-      new URL(
-        "../../../../../tests/_islands/snapshots/html-payload.txt",
-        import.meta.url,
-      ).pathname.replace(/^\/@fs/, ""),
-      "utf8",
-    );
+    const html = readFileSync(islandSnapshotPath("html-payload.txt"), "utf8");
     container.innerHTML = html;
 
     const result = parseMarimoIslandApps(container);
@@ -775,6 +804,108 @@ describe("parseMarimoIslandApps", () => {
     expect(islands[2].getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX)).toBe("1");
   });
 
+  it("should restore metadata from a Python-generated dependency payload", () => {
+    container.innerHTML = readFileSync(
+      islandSnapshotPath("body-dependencies.txt"),
+      "utf8",
+    );
+
+    const probed = parseMarimoIslandApps(container, { materialize: false });
+    const apps = parseMarimoIslandApps(container);
+
+    expect(probed).toEqual(apps);
+    expect(apps).toEqual([
+      {
+        id: "main",
+        payloadBacked: true,
+        dependencies: [
+          'cowsay==6.1; sys_platform == "emscripten"',
+          "rich[jupyter]>=13",
+          "desktop; sys_platform != 'emscripten'",
+          "older-python; python_version < '3.13'",
+          "newer-python; python_version >= '3.13'",
+        ],
+        cells: [{ cellId: "Hbol", code: "import cowsay", output: "", idx: 0 }],
+      },
+    ]);
+    // The Python Pyodide test reads this file with the real metadata parser.
+    expect(createMarimoFile(apps[0])).toBe(
+      readFileSync(islandSnapshotPath("notebook-dependencies.txt"), "utf8"),
+    );
+  });
+
+  it("should carry dependencies from payloads into each generated notebook", () => {
+    for (const [appId, dependencies] of [
+      ["app1", ["cowsay==6.1"]],
+      ["app2", ["rich[jupyter]>=13"]],
+    ] as const) {
+      container.appendChild(
+        createMockIslandElement({ appId, cellId: "cell-1" }),
+      );
+      appendPayload(container, {
+        schemaVersion: 1,
+        appId,
+        dependencies,
+        cells: [createPayloadCell()],
+      });
+    }
+
+    const apps = parseMarimoIslandApps(container);
+    expect(apps.map((app) => [app.id, app.dependencies])).toEqual([
+      ["app1", ["cowsay==6.1"]],
+      ["app2", ["rich[jupyter]>=13"]],
+    ]);
+    expect(createMarimoFile(apps[0])).toContain(
+      '# /// script\n# dependencies = ["cowsay==6.1"]\n# ///\n',
+    );
+  });
+
+  it.each([null, "cowsay", [123], ["cowsay", null]])(
+    "should ignore payloads with malformed dependencies: %j",
+    (dependencies) => {
+      const island = createMockIslandElement({
+        appId: "app1",
+        cellId: "cell-1",
+        code: "import cowsay",
+        innerHTML: "<div>dom</div>",
+      });
+      island.setAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE, "true");
+      container.appendChild(island);
+      appendPayload(container, {
+        schemaVersion: 1,
+        appId: "app1",
+        dependencies,
+        cells: [createPayloadCell()],
+      });
+
+      expect(parseMarimoIslandApps(container)).toEqual([
+        {
+          id: "app1",
+          cells: [{ code: "import cowsay", output: "<div>dom</div>", idx: 0 }],
+        },
+      ]);
+    },
+  );
+
+  it("should merge dependencies from payloads belonging to the same app", () => {
+    for (const [cellId, dependencies] of [
+      ["cell-1", ["cowsay"]],
+      ["cell-2", ["cowsay", "rich"]],
+    ] as const) {
+      container.appendChild(createMockIslandElement({ appId: "app1", cellId }));
+      appendPayload(container, {
+        schemaVersion: 1,
+        appId: "app1",
+        dependencies,
+        cells: [createPayloadCell({ cellId })],
+      });
+    }
+
+    expect(
+      parseMarimoIslandApps(container).map((app) => app.dependencies),
+    ).toEqual([["cowsay", "rich"]]);
+  });
+
   it("should fall back to DOM islands for unsupported payload versions", () => {
     const island = createMockIslandElement({
       appId: "app1",
@@ -990,6 +1121,7 @@ describe("parseMarimoIslandApps", () => {
           outputHtml: "<div>payload only</div>",
         }),
       ],
+      dependencies: ["cowsay"],
     });
 
     const result = parseMarimoIslandApps(container);
@@ -1076,6 +1208,7 @@ describe("parseMarimoIslandApps", () => {
           reactive: false,
         }),
       ],
+      dependencies: ["cowsay"],
     });
 
     const result = parseMarimoIslandApps(container);

package/src/core/islands/parse.ts

@@ -30,6 +30,8 @@ export interface MarimoIslandApp {
    * Whether cells came from a supported JSON payload instead of DOM parsing.
    */
   payloadBacked?: boolean;
+  /** Explicit notebook dependencies to install before starting the app. */
+  dependencies?: string[];
   /**
    * Cells in the app.
    */
@@ -62,6 +64,7 @@ interface MarimoIslandCell {
 interface MarimoIslandPayload {
   schemaVersion: 1;
   appId: string;
+  dependencies?: string[];
   cells: MarimoIslandPayloadCell[];
 }
 
@@ -235,6 +238,12 @@ function parsePayloadBackedApps({
         embed?.setAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX, idx.toString());
       }
     }
+    const app = apps.get(payload.appId);
+    if (app && payload.dependencies?.length) {
+      app.dependencies = [
+        ...new Set([...(app.dependencies ?? []), ...payload.dependencies]),
+      ];
+    }
   }
 
   // A supported payload is the runtime source for its app. Extra same-app DOM
@@ -371,6 +380,7 @@ export function parseIslandElement(
 
 export function createMarimoFile(app: {
   cells: { code: string; disabled?: boolean }[];
+  dependencies?: string[];
 }): string {
   const lines = [
     "import marimo",
@@ -402,6 +412,13 @@ export function createMarimoFile(app: {
       .join("\n"),
   ];
 
+  if (app.dependencies?.length) {
+    lines.unshift(
+      "# /// script",
+      `# dependencies = ${JSON.stringify(app.dependencies)}`,
+      "# ///",
+    );
+  }
   return lines.join("\n");
 }
 
@@ -507,6 +524,9 @@ function isMarimoIslandPayload(
   return (
     payload.schemaVersion === 1 &&
     typeof payload.appId === "string" &&
+    (payload.dependencies === undefined ||
+      (Array.isArray(payload.dependencies) &&
+        payload.dependencies.every((dep) => typeof dep === "string"))) &&
     Array.isArray(payload.cells) &&
     payload.cells.every(isMarimoIslandPayloadCell)
   );

package/src/core/packages/__tests__/useInstallPackage.test.tsx

@@ -1,10 +1,22 @@
 /* Copyright 2026 Marimo. All rights reserved. */
-import { act, renderHook } from "@testing-library/react";
+import {
+  act,
+  fireEvent,
+  render,
+  renderHook,
+  screen,
+} from "@testing-library/react";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { useInstallPackages } from "../useInstallPackage";
+import { Toast, ToastProvider, ToastViewport } from "@/components/ui/toast";
 
 const toast = vi.fn();
 const addPackage = vi.fn();
+const restartKernel = vi.fn();
+
+vi.mock("@/components/editor/actions/useRestartKernel", () => ({
+  useRestartKernel: () => restartKernel,
+}));
 
 vi.mock("@/components/ui/use-toast", () => ({
   toast: (...args: unknown[]) => toast(...args),
@@ -20,6 +32,7 @@ describe("useInstallPackages", () => {
   beforeEach(() => {
     toast.mockClear();
     addPackage.mockClear();
+    restartKernel.mockClear();
   });
 
   it("batches all packages into a single install call", async () => {
@@ -109,6 +122,39 @@ describe("useInstallPackages", () => {
     );
   });
 
+  it("reports saved changes requiring restart without claiming installation", async () => {
+    addPackage.mockResolvedValue({
+      success: false,
+      error: null,
+      restartRequired: true,
+    });
+    const { result } = renderHook(() => useInstallPackages());
+    await act(async () => {
+      await result.current.handleInstallPackages(["boltons", "six"]);
+    });
+    expect(toast).toHaveBeenCalledTimes(1);
+    expect(toast).toHaveBeenCalledWith(
+      expect.objectContaining({
+        title: "Changes saved — restart required",
+        description: expect.stringContaining(
+          "Restarting clears in-memory variables",
+        ),
+        duration: Infinity,
+        action: expect.anything(),
+      }),
+    );
+    expect(toast.mock.calls[0][0].variant).not.toBe("danger");
+    render(
+      <ToastProvider>
+        <Toast>{toast.mock.calls[0][0].action}</Toast>
+        <ToastViewport />
+      </ToastProvider>,
+    );
+    expect(restartKernel).not.toHaveBeenCalled();
+    fireEvent.click(screen.getByRole("button", { name: "Restart Kernel" }));
+    expect(restartKernel).toHaveBeenCalledTimes(1);
+  });
+
   it("calls onSuccess after a successful install", async () => {
     addPackage.mockResolvedValue({ success: true, error: null });
     const onSuccess = vi.fn();

package/src/core/packages/toast-components.tsx

@@ -1,8 +1,34 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
+import { useRestartKernel } from "@/components/editor/actions/useRestartKernel";
 import { Kbd } from "@/components/ui/kbd";
+import { ToastAction } from "@/components/ui/toast";
 import { toast } from "@/components/ui/use-toast";
 
+export const RESTART_REQUIRED_DESCRIPTION =
+  "Your dependency changes are saved. Restart the kernel to use the updated environment. Restarting clears in-memory variables.";
+
+const RestartKernelAction = () => {
+  const restartKernel = useRestartKernel();
+  return (
+    <ToastAction
+      altText="Restart the kernel to use the updated dependencies"
+      onClick={restartKernel}
+    >
+      Restart Kernel
+    </ToastAction>
+  );
+};
+
+export const showPackageRestartToast = () => {
+  toast({
+    title: "Changes saved — restart required",
+    description: RESTART_REQUIRED_DESCRIPTION,
+    duration: Infinity,
+    action: <RestartKernelAction />,
+  });
+};
+
 export const showAddPackageToast = (
   packageName: string | string[],
   error?: string | null,

package/src/core/packages/useInstallPackage.ts

@@ -3,7 +3,10 @@
 import { useState } from "react";
 import { Logger } from "@/utils/Logger";
 import { useRequestClient } from "../network/requests";
-import { showAddPackageToast } from "./toast-components";
+import {
+  showAddPackageToast,
+  showPackageRestartToast,
+} from "./toast-components";
 
 export function useInstallPackages(): {
   handleInstallPackages: (
@@ -30,7 +33,9 @@ export function useInstallPackages(): {
       // response only carries an aggregate success/error. Report a single
       // toast covering all requested packages rather than implying a
       // per-package outcome we don't actually have.
-      if (response.success) {
+      if (response.restartRequired) {
+        showPackageRestartToast();
+      } else if (response.success) {
         showAddPackageToast(packages);
       } else {
         showAddPackageToast(packages, response.error);

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

@@ -276,6 +276,17 @@ describe("RuntimeManager", () => {
   });
 
   describe("getTerminalWsURL", () => {
+    it("should include dimensions in the terminal handshake", () => {
+      const runtime = new RuntimeManager(mockConfig);
+      const url = runtime.getTerminalWsURL({ rows: 30, cols: 140 });
+
+      expect(Object.fromEntries(url.searchParams)).toEqual({
+        access_token: "test-token",
+        rows: "30",
+        cols: "140",
+      });
+    });
+
     it("should return terminal WebSocket URL", () => {
       const runtime = new RuntimeManager(mockConfig);
       const url = runtime.getTerminalWsURL();