@marimo-team/islands 0.24.3-dev5 → 0.24.3-dev50

package/src/core/edit-app.tsx

@@ -9,7 +9,8 @@ import { useAtomValue, useSetAtom } from "jotai";
 import { useEffect } from "react";
 import { NotStartedConnectionAlert } from "@/components/editor/alerts/connecting-alert";
 import { Controls } from "@/components/editor/controls/Controls";
-import { AppHeader } from "@/components/editor/header/app-header";
+import { SandboxController } from "@/components/editor/chrome/panels/sandbox-controller";
+import { ConnectionNotice } from "@/components/editor/alerts/connection-notice";
 import { FilenameForm } from "@/components/editor/header/filename-form";
 import { MultiCellActionToolbar } from "@/components/editor/navigation/multi-cell-action-toolbar";
 import { ViewerBanner } from "@/components/editor/viewer-banner";
@@ -158,6 +159,7 @@ export const EditApp: React.FC<AppProps> = ({
 
   return (
     <>
+      <SandboxController onReconnect={reconnect} />
       <AppContainer
         connection={connection}
         isRunning={isRunning}
@@ -165,10 +167,9 @@ export const EditApp: React.FC<AppProps> = ({
         onReconnect={reconnect}
       >
         <ViewerBanner />
-        <AppHeader
-          connection={connection}
+        <div
           className={cn(
-            "pt-4 sm:pt-12 pb-2 mb-4 print:hidden z-50",
+            "pt-4 sm:pt-12 pb-6 print:hidden z-50",
             // Keep the header sticky when scrolling horizontally, for column mode
             "sticky left-0",
           )}
@@ -178,7 +179,9 @@ export const EditApp: React.FC<AppProps> = ({
               <FilenameForm filename={filename} />
             </div>
           )}
-        </AppHeader>
+        </div>
+
+        <ConnectionNotice appConfig={appConfig} onRetry={reconnect} />
 
         {/* Don't render until we have a single cell. NotStartedConnectionAlert
             still covers the "no remote runtime started" prompt. */}

package/src/core/errors/state.ts

@@ -7,8 +7,7 @@ import { generateUUID } from "@/utils/uuid";
 import type { Banner } from "../kernel/messages";
 
 /**
- * Atom for storing kernel startup error message.
- * When set to a non-null value, shows a modal with the error details.
+ * Full startup diagnostics, retained until a new connection attempt or readiness.
  */
 export const kernelStartupErrorAtom = atom<string | null>(null);
 

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/bootstrap.ts

@@ -201,6 +201,7 @@ function handleMessage(
       case "storage-download-ready":
       case "secret-keys-result":
       case "startup-logs":
+      case "startup-progress":
       case "interrupted":
       case "reconnected":
       case "cache-cleared":

package/src/core/islands/bridge.ts

@@ -370,6 +370,9 @@ export class IslandsPyodideBridge implements RunRequests, EditRequests {
   addPackage = throwNotImplemented;
   removePackage = throwNotImplemented;
   getPackageList = throwNotImplemented;
+  getSandbox = throwNotImplemented;
+  updateManifest = throwNotImplemented;
+  syncSandbox = throwNotImplemented;
   getDependencyTree = throwNotImplemented;
   getRecentFiles = throwNotImplemented;
   getWorkspaceFiles = throwNotImplemented;

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/network/connection-notice.ts

@@ -0,0 +1,84 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { atom } from "jotai";
+import { kernelStartupErrorAtom } from "@/core/errors/state";
+import { sandboxAtom, sandboxSyncAtom } from "@/core/packages/sandbox-state";
+import { WebSocketClosedReason, WebSocketState } from "@/core/websocket/types";
+import { connectionAtom } from "./connection";
+
+export const connectionNoticeAtom = atom((get) => {
+  const connection = get(connectionAtom);
+  const backend = get(sandboxAtom)?.backend;
+  const sandbox = Boolean(backend);
+  const sync = get(sandboxSyncAtom);
+  if (
+    sandbox &&
+    (sync.pending || sync.error) &&
+    connection.state === WebSocketState.OPEN
+  ) {
+    return {
+      sandbox,
+      title: sync.pending ? "Syncing sandbox…" : "Sandbox sync failed",
+      description: sync.pending
+        ? "Applying the saved manifest to this notebook’s environment."
+        : "Review the error details, then try again.",
+      pending: sync.pending,
+      error: sync.error,
+    };
+  }
+  if (connection.state === WebSocketState.CONNECTING) {
+    const messages = {
+      "preparing-environment": {
+        title: backend
+          ? `Preparing ${backend} sandbox…`
+          : "Preparing environment…",
+        description:
+          "Getting this notebook’s Python environment ready. The first start can take a few minutes.",
+      },
+      "starting-kernel": {
+        title: "Starting notebook…",
+        description:
+          "The environment is prepared. Waiting for the Python kernel to connect to this notebook.",
+      },
+      reconnecting: {
+        title: "Reconnecting…",
+        description:
+          "The connection was interrupted. Your notebook and existing outputs stay visible while the kernel reconnects.",
+      },
+    };
+    return {
+      sandbox,
+      ...(connection.phase
+        ? messages[connection.phase]
+        : {
+            title: "Connecting…",
+            description: "Waiting for the notebook’s kernel to connect.",
+          }),
+      pending: true,
+      error: null,
+    };
+  }
+  if (connection.state === WebSocketState.CLOSED) {
+    const startupFailed =
+      connection.code === WebSocketClosedReason.KERNEL_STARTUP_ERROR;
+    const environmentFailed =
+      startupFailed && connection.phase === "preparing-environment";
+    return {
+      sandbox,
+      title: environmentFailed
+        ? "Sandbox setup failed"
+        : startupFailed
+          ? "Kernel failed to start"
+          : connection.reason,
+      description: environmentFailed
+        ? "The notebook can’t run yet."
+        : startupFailed
+          ? "The Python kernel could not start. Check the error details, then try again."
+          : "The connection to the notebook’s kernel was lost.",
+      pending: false,
+      error: startupFailed
+        ? (get(kernelStartupErrorAtom) ?? connection.reason)
+        : null,
+    };
+  }
+  return null;
+});

package/src/core/network/requests-lazy.ts

@@ -93,6 +93,9 @@ const ACTIONS: Record<keyof AllRequests, Action> = {
   saveUserConfig: "throwError",
   sendShutdown: "throwError",
   getPackageList: "throwError",
+  getSandbox: "serverOnly",
+  updateManifest: "serverOnly",
+  syncSandbox: "serverOnly",
   getDependencyTree: "throwError",
   addPackage: "throwError",
   removePackage: "throwError",

package/src/core/network/requests-network.ts

@@ -532,6 +532,18 @@ export function createNetworkRequests(): EditRequests & RunRequests {
         })
         .then(handleResponseReturnNull);
     },
+    getSandbox: (request) =>
+      getClient()
+        .POST("/api/packages/sandbox", { body: request, params: getParams() })
+        .then(handleResponse),
+    updateManifest: (request) =>
+      getClient()
+        .POST("/api/packages/manifest", { body: request, params: getParams() })
+        .then(handleResponse),
+    syncSandbox: (request) =>
+      getClient()
+        .POST("/api/packages/sync", { body: request, params: getParams() })
+        .then(handleResponse),
     addPackage: (request) => {
       return getClient()
         .POST("/api/packages/add", {

package/src/core/network/requests-static.ts

@@ -98,6 +98,9 @@ export function createStaticRequests(): EditRequests & RunRequests {
     addPackage: throwNotInEditMode,
     removePackage: throwNotInEditMode,
     getPackageList: throwNotInEditMode,
+    getSandbox: throwNotInEditMode,
+    updateManifest: throwNotInEditMode,
+    syncSandbox: throwNotInEditMode,
     getDependencyTree: throwNotInEditMode,
     listSecretKeys: throwNotInEditMode,
     writeSecret: throwNotInEditMode,

package/src/core/network/requests-toasting.tsx

@@ -79,6 +79,9 @@ export function createErrorToastingRequests(
     addPackage: "Failed to add package",
     removePackage: "Failed to remove package",
     getPackageList: "Failed to get package list",
+    getSandbox: "",
+    updateManifest: "",
+    syncSandbox: "",
     getDependencyTree: "Failed to get dependency tree",
     listSecretKeys: "Failed to fetch secrets",
     writeSecret: "Failed to write secret",

package/src/core/network/resolve.ts

@@ -1,4 +1,5 @@
 /* Copyright 2026 Marimo. All rights reserved. */
+import { withPackageInvalidation } from "../packages/package-data";
 import { getRuntimeManager } from "../runtime/config";
 import { isStaticNotebook } from "../static/static-state";
 import { PyodideBridge } from "../wasm/bridge";
@@ -20,5 +21,5 @@ export function resolveRequestClient(): EditRequests & RunRequests {
       getRuntimeManager(),
     );
   }
-  return createErrorToastingRequests(base);
+  return withPackageInvalidation(createErrorToastingRequests(base));
 }

package/src/core/network/types.ts

@@ -69,6 +69,10 @@ export type ListPackagesResponse = schemas["ListPackagesResponse"];
 export type DependencyTreeResponse = schemas["DependencyTreeResponse"];
 export type DependencyTreeNode = schemas["DependencyTreeNode"];
 
+export type SandboxRequest = schemas["SandboxRequest"];
+export type SandboxResponse = schemas["SandboxResponse"];
+export type UpdateManifestRequest = schemas["UpdateManifestRequest"];
+export type SyncSandboxResponse = schemas["SyncSandboxResponse"];
 export type PackageOperationResponse = schemas["PackageOperationResponse"];
 export type InstantiateNotebookRequest = schemas["InstantiateNotebookRequest"];
 export type MarimoConfig = schemas["MarimoConfig"];
@@ -246,6 +250,9 @@ export interface EditRequests {
   autoExportAsMarkdown: (request: AutoExportAsMarkdownRequest) => Promise<null>;
   autoExportAsIPYNB: (request: AutoExportAsIPYNBRequest) => Promise<null>;
   updateCellOutputs: (request: UpdateCellOutputsRequest) => Promise<null>;
+  getSandbox: (request: SandboxRequest) => Promise<SandboxResponse>;
+  updateManifest: (request: UpdateManifestRequest) => Promise<SandboxResponse>;
+  syncSandbox: (request: SandboxRequest) => Promise<SyncSandboxResponse>;
   // Package requests
   getPackageList: () => Promise<ListPackagesResponse>;
   getDependencyTree: () => Promise<DependencyTreeResponse>;

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

@@ -0,0 +1,129 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { act, renderHook } from "@testing-library/react";
+import { createStore, Provider } from "jotai";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { MockRequestClient } from "@/__mocks__/requests";
+import { toast } from "@/components/ui/use-toast";
+import { requestClientAtom } from "@/core/network/requests";
+import type { PackageOperationResponse } from "@/core/network/types";
+import { usePackageAction } from "../usePackageAction";
+
+vi.mock("@/components/ui/use-toast", () => ({ toast: vi.fn() }));
+
+function setup(action: "upgrade" | "remove") {
+  const client = MockRequestClient.create();
+  const store = createStore();
+  store.set(requestClientAtom, client);
+  return {
+    request: vi.mocked(
+      action === "upgrade" ? client.addPackage : client.removePackage,
+    ),
+    ...renderHook(
+      () =>
+        usePackageAction(action, "numpy", [{ kind: "group", value: "dev" }]),
+      {
+        wrapper: ({ children }) => (
+          <Provider store={store}>{children}</Provider>
+        ),
+      },
+    ),
+  };
+}
+
+describe("usePackageAction", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it.each([
+    { action: "upgrade", title: "Package upgraded", upgrade: true },
+    { action: "remove", title: "Package removed" },
+  ] as const)(
+    "preserves dependency groups and prevents duplicate $action requests",
+    async ({ action, title, ...options }) => {
+      const { result, request } = setup(action);
+      const { promise, resolve } =
+        Promise.withResolvers<PackageOperationResponse>();
+      request.mockReturnValue(promise);
+      let pending: Promise<void>;
+      act(() => {
+        pending = result.current.run();
+      });
+      expect(result.current.loading).toBe(true);
+      await act(async () => {
+        await result.current.run();
+      });
+      expect(request).toHaveBeenCalledExactlyOnceWith({
+        package: "numpy",
+        group: "dev",
+        ...options,
+      });
+      await act(async () => {
+        resolve({ success: true });
+        await pending;
+      });
+      expect(result.current.loading).toBe(false);
+      expect(toast).toHaveBeenCalledExactlyOnceWith(
+        expect.objectContaining({ title }),
+      );
+    },
+  );
+
+  it("reports saved changes requiring a restart without claiming success", async () => {
+    const { result, request } = setup("upgrade");
+    request.mockResolvedValue({ success: false, restartRequired: true });
+    await act(async () => {
+      await result.current.run();
+    });
+    expect(toast).toHaveBeenCalledExactlyOnceWith(
+      expect.objectContaining({
+        title: "Changes saved — restart required",
+      }),
+    );
+  });
+
+  it.each([
+    {
+      response: { success: false, error: "resolver failed" },
+      description: "resolver failed",
+    },
+    { response: { success: false }, description: expect.any(String) },
+  ])(
+    "reports failed responses as errors: $response",
+    async ({ response, description }) => {
+      const { result, request } = setup("remove");
+      request.mockResolvedValue(response);
+      await act(async () => {
+        await result.current.run();
+      });
+      expect(toast).toHaveBeenCalledExactlyOnceWith(
+        expect.objectContaining({
+          title: "Failed to remove package",
+          description,
+          variant: "danger",
+        }),
+      );
+    },
+  );
+
+  it("reports request errors and allows a retry", async () => {
+    const { result, request } = setup("remove");
+    request.mockRejectedValueOnce(new Error("offline"));
+    await act(async () => {
+      await result.current.run();
+    });
+    expect(toast).toHaveBeenCalledExactlyOnceWith(
+      expect.objectContaining({
+        title: "Failed to remove package",
+        description: "offline",
+        variant: "danger",
+      }),
+    );
+    expect(result.current.loading).toBe(false);
+    request.mockResolvedValue({ success: true });
+    await act(async () => {
+      await result.current.run();
+    });
+    expect(toast).toHaveBeenLastCalledWith(
+      expect.objectContaining({ title: "Package removed" }),
+    );
+  });
+});