@marimo-team/islands 0.24.3-dev0 → 0.24.3-dev10

package/src/components/editor/package-alert.tsx

@@ -10,6 +10,7 @@ import {
   PackageCheckIcon,
   PackageXIcon,
   PlusIcon,
+  RotateCwIcon,
   XIcon,
 } from "lucide-react";
 import type React from "react";
@@ -32,6 +33,7 @@ import {
 import { useResolvedMarimoConfig } from "@/core/config/config";
 import type { PackageInstallationStatus } from "@/core/kernel/messages";
 import { useRequestClient } from "@/core/network/requests";
+import { RESTART_REQUIRED_DESCRIPTION } from "@/core/packages/toast-components";
 import { isWasm } from "@/core/wasm/utils";
 import { usePackageMetadata } from "@/hooks/usePackageMetadata";
 import { Banner } from "@/plugins/impl/common/error-banner";
@@ -55,6 +57,12 @@ import {
 import { ExternalLink } from "../ui/links";
 import { NativeSelect } from "../ui/native-select";
 import { Tooltip } from "../ui/tooltip";
+import { useRestartKernel } from "./actions/useRestartKernel";
+
+const RestartKernelButton = () => {
+  const restartKernel = useRestartKernel();
+  return <Button onClick={restartKernel}>Restart Kernel</Button>;
+};
 
 function parsePackageSpecifier(spec: string): {
   name: string;
@@ -251,6 +259,10 @@ export const PackageAlert: React.FC = () => {
             )}
           >
             <p>{description}</p>
+            {status !== "installing" &&
+              Object.values(packageAlert.packages).includes(
+                "restart-required",
+              ) && <RestartKernelButton />}
             <ul className="list-disc ml-2 mt-1">
               {Object.entries(packageAlert.packages).map(([pkg, st], index) => (
                 <li
@@ -290,7 +302,9 @@ function getInstallationStatusElements(packages: PackageInstallationStatus) {
       ? "installing"
       : statuses.has("failed")
         ? "failed"
-        : "installed";
+        : statuses.has("restart-required")
+          ? "restart-required"
+          : "installed";
 
   if (status === "installing") {
     return {
@@ -300,6 +314,14 @@ function getInstallationStatusElements(packages: PackageInstallationStatus) {
       description: "Installing packages:",
     };
   }
+  if (status === "restart-required") {
+    return {
+      status,
+      title: "Changes saved — restart required",
+      titleIcon: <RotateCwIcon className="w-5 h-5 inline-block mr-2" />,
+      description: RESTART_REQUIRED_DESCRIPTION,
+    };
+  }
   if (status === "installed") {
     return {
       status: "installed",
@@ -330,6 +352,8 @@ const ProgressIcon = ({
       return <CheckIcon size="1rem" />;
     case "failed":
       return <XIcon size="1rem" />;
+    case "restart-required":
+      return <RotateCwIcon size="1rem" />;
     default:
       logNever(status);
       return null;

package/src/components/home/components.tsx

@@ -31,6 +31,7 @@ import {
 import { Constants } from "@/core/constants";
 import { useRequestClient } from "@/core/network/requests";
 import type { TutorialId } from "@/core/network/types";
+import { Banner } from "@/plugins/impl/common/error-banner";
 import { openNotebook } from "@/utils/links";
 import { Objects } from "@/utils/objects";
 import { MarimoPlusIcon } from "../icons/marimo-icons";
@@ -186,6 +187,22 @@ export const ResourceLinks: React.FC = () => {
   );
 };
 
+/**
+ * Shown when the workspace scan stopped early, so the file list the user is
+ * looking at is missing files and folders.
+ */
+export const TruncatedWorkspaceBanner: React.FC<{
+  fileCount: number | undefined;
+}> = ({ fileCount }) => {
+  return (
+    <Banner kind="warn" className="rounded p-4">
+      Showing {fileCount} files. Some files and folders were skipped because
+      your workspace is large or deeply nested. Start marimo from a subfolder to
+      see them.
+    </Banner>
+  );
+};
+
 export const Header: React.FC<{
   Icon: React.FC<React.SVGProps<SVGSVGElement>>;
   control?: React.ReactNode;

package/src/components/pages/gallery-page.tsx

@@ -4,6 +4,7 @@ import { SearchIcon } from "lucide-react";
 import type React from "react";
 import { Suspense, useMemo, useState } from "react";
 import { ErrorBoundary } from "@/components/editor/boundary/ErrorBoundary";
+import { TruncatedWorkspaceBanner } from "@/components/home/components";
 import { Spinner } from "@/components/icons/spinner";
 import { Card, CardContent } from "@/components/ui/card";
 import { Input } from "@/components/ui/input";
@@ -119,10 +120,7 @@ const GalleryPage: React.FC = () => {
         <ErrorBoundary>
           <div className="flex flex-col gap-2">
             {workspace.hasMore && (
-              <Banner kind="warn" className="rounded p-4">
-                Showing first {workspace.fileCount} files. Your workspace has
-                more files.
-              </Banner>
+              <TruncatedWorkspaceBanner fileCount={workspace.fileCount} />
             )}
             {formattedFiles.length > SEARCH_THRESHOLD && (
               <Input

package/src/components/pages/home-page.tsx

@@ -67,6 +67,7 @@ import {
   Header,
   OpenTutorialDropDown,
   ResourceLinks,
+  TruncatedWorkspaceBanner,
 } from "../home/components";
 import {
   expandedFoldersAtom,
@@ -196,10 +197,7 @@ const WorkspaceNotebooks: React.FC<{ onRefreshRecents: () => void }> = ({
     <WorkspaceContext value={workspaceContextValue}>
       <div className="flex flex-col gap-2">
         {workspace.hasMore && (
-          <Banner kind="warn" className="rounded p-4">
-            Showing first {workspace.fileCount} files. Your workspace has more
-            files.
-          </Banner>
+          <TruncatedWorkspaceBanner fileCount={workspace.fileCount} />
         )}
         <Header
           Icon={BookTextIcon}

package/src/components/terminal/terminal.tsx

@@ -254,7 +254,9 @@ const TerminalComponent: React.FC<TerminalComponentProps> = ({
       try {
         await waitForConnectionOpen();
 
-        const socket = new WebSocket(runtimeManager.getTerminalWsURL());
+        // Size the PTY before the shell draws its first prompt.
+        fitAddon.fit();
+        const socket = new WebSocket(runtimeManager.getTerminalWsURL(terminal));
         const attachAddon = new AttachAddon(socket);
         terminal.loadAddon(attachAddon);
         wsRef.current = socket;
@@ -270,9 +272,7 @@ const TerminalComponent: React.FC<TerminalComponentProps> = ({
 
         const handleOpen = () => {
           updateReadyState();
-          // Send initial dimensions: the mount-time fit() may have fired
-          // before the WS was OPEN, dropping the resize message and leaving
-          // the PTY at its default 0x0 winsize.
+          // The container may have resized while the connection was opening.
           fitAddon.fit();
           if (terminal.cols > 0 && terminal.rows > 0) {
             socket.send(

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

@@ -49,7 +49,14 @@ describe("runDuringPresentMode", () => {
     store.set(viewStateAtom, state);
 
     const result = runDuringPresentMode(() => Promise.reject(error));
-    const rejection = expect(result).rejects.toBe(error);
+    const rejection = result.then(
+      () => {
+        throw new Error("Expected runDuringPresentMode to reject");
+      },
+      (caughtError: unknown) => {
+        expect(caughtError).toBe(error);
+      },
+    );
     await vi.runAllTimersAsync();
     await rejection;
 

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();

package/src/core/runtime/runtime.ts

@@ -183,8 +183,13 @@ export class RuntimeManager {
   /**
    * The WebSocket URL of the terminal.
    */
-  getTerminalWsURL(): URL {
-    return this.formatWsURL("/terminal/ws");
+  getTerminalWsURL(size?: { rows: number; cols: number }): URL {
+    const url = this.formatWsURL("/terminal/ws");
+    if (size) {
+      url.searchParams.set("rows", String(size.rows));
+      url.searchParams.set("cols", String(size.cols));
+    }
+    return url;
   }
 
   /**

package/src/core/wasm/bridge.ts

@@ -649,6 +649,7 @@ export class PyodideBridge implements RunRequests, EditRequests {
         tags: [],
         version: null,
       },
+      context: { kind: "package-manager", name: "micropip" },
     };
   };