@marimo-team/islands 0.24.3-dev9 → 0.25.0

package/src/core/config/pair.ts

@@ -0,0 +1,19 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { atom } from "jotai";
+import { z } from "zod";
+
+export const pairPreviewSchema = z.object({
+  command: z.string(),
+  templates: z.object({
+    prompt: z.string(),
+    file: z.string(),
+    session: z.string(),
+    token_file: z.string(),
+    token: z.string(),
+  }),
+});
+
+export type PairPreviewConfig = z.infer<typeof pairPreviewSchema>;
+
+export const pairPreviewAtom = atom<PairPreviewConfig | undefined>(undefined);

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/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/export/__tests__/hooks.test.ts

@@ -552,12 +552,7 @@ describe("useEnrichCellOutputs", () => {
     // Verify the exact return type structure
     expect(output).toHaveProperty(cid);
     const cellOutput = output[cid];
-    expect(cellOutput).toBeDefined();
-    expect(Array.isArray(cellOutput)).toBe(true);
-    if (cellOutput) {
-      expect(cellOutput[0]).toBe("image/png");
-      expect(cellOutput[1]).toBe(mockDataUrl);
-    }
+    expect(cellOutput).toEqual(["image/png", mockDataUrl]);
   });
 });
 

package/src/core/islands/bootstrap.ts

@@ -181,7 +181,8 @@ function handleMessage(
       // Unsupported operations in islands mode
       case "banner":
       case "missing-package-alert":
-      case "installing-package-alert":
+      case "environment-operation":
+      case "environment-state":
       case "completion-result":
       case "reload":
       case "focus-cell":
@@ -201,6 +202,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/worker-factory.ts

@@ -1,5 +1,6 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
+import { createModuleWorker } from "@/utils/worker";
 import { getMarimoVersion } from "../meta/globals";
 import workerUrl from "./worker/worker.tsx?worker&url";
 
@@ -47,20 +48,9 @@ export class DefaultWorkerFactory implements WorkerFactory {
    * Creates a new Pyodide worker
    */
   create(): Worker {
-    const js = `import ${JSON.stringify(new URL(this.url, import.meta.url))}`;
-    const blob = new Blob([js], { type: "application/javascript" });
-    const objURL = URL.createObjectURL(blob);
-
-    const worker = new Worker(objURL, {
-      type: "module",
-      /* @vite-ignore */
+    return createModuleWorker(new URL(this.url, import.meta.url), {
       name: this.name,
     });
-
-    // Blob URL can be revoked once the worker has loaded the script
-    URL.revokeObjectURL(objURL);
-
-    return worker;
   }
 
   /**

package/src/core/kernel/messages.ts

@@ -36,8 +36,8 @@ export type CompletionResultMessage =
 export type HumanReadableStatus = schemas["HumanReadableStatus"];
 export type FunctionCallResultMessage =
   NotificationMessageData<"function-call-result">;
-export type PackageInstallationStatus =
-  schemas["InstallingPackageAlertNotification"]["packages"];
+export type PackageOperationStatus =
+  schemas["EnvironmentOperationNotification"]["packages"];
 export type DataColumnPreview = NotificationMessageData<"data-column-preview">;
 export type SQLTablePreview = NotificationMessageData<"sql-table-preview">;
 export type SQLTableListPreview =

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

@@ -69,9 +69,10 @@ describe("createNetworkRequests", () => {
     const methodNames = Object.keys(requests);
 
     for (const methodName of methodNames) {
-      if (!ACTIONS[methodName as keyof typeof ACTIONS]) {
-        expect.fail(`Method ${methodName} has no action defined`);
-      }
+      expect(
+        ACTIONS[methodName as keyof typeof ACTIONS],
+        `Method ${methodName} has no action defined`,
+      ).toBeDefined();
     }
   });
 

package/src/core/network/connection-notice.ts

@@ -0,0 +1,117 @@
+/* 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 {
+  type ConnectionPhase,
+  WebSocketClosedReason,
+  WebSocketState,
+} from "@/core/websocket/types";
+import { connectionAtom } from "./connection";
+
+export interface ConnectionNotice {
+  kind: "startup" | "sync" | "connection";
+  phase?: ConnectionPhase;
+  sandbox: boolean;
+  title: string;
+  description: string;
+  pending: boolean;
+  error: string | null;
+}
+
+export const connectionNoticeAtom = atom<ConnectionNotice | null>((get) => {
+  const connection = get(connectionAtom);
+  const backend = get(sandboxAtom)?.backend;
+  const sandbox = Boolean(backend);
+  const sync = get(sandboxSyncAtom);
+  const syncing = sync.kind === "running";
+  const restartRequired = sync.kind === "restart-required";
+  const syncError =
+    sync.kind === "failed"
+      ? sync.error
+      : sync.kind === "cancelled"
+        ? "Sandbox sync was interrupted."
+        : restartRequired
+          ? sync.reason
+          : null;
+  if (
+    sandbox &&
+    (syncing || syncError !== null) &&
+    connection.state === WebSocketState.OPEN
+  ) {
+    return {
+      kind: "sync",
+      sandbox,
+      title: syncing
+        ? "Syncing sandbox…"
+        : restartRequired
+          ? "Sandbox restart required"
+          : "Sandbox sync failed",
+      description: syncing
+        ? "Applying the saved manifest to this notebook’s environment."
+        : restartRequired
+          ? "Restart the kernel to use the updated environment."
+          : "Review the error details, then try again.",
+      pending: syncing,
+      error: syncError,
+    };
+  }
+  if (connection.state === WebSocketState.CONNECTING) {
+    const messages = {
+      "preparing-environment": {
+        title: "Preparing environment…",
+        description:
+          "Getting this notebook’s Python environment ready. The first start can take a few minutes.",
+      },
+      "starting-kernel": {
+        title: "Starting kernel…",
+        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 {
+      kind: connection.phase === "reconnecting" ? "connection" : "startup",
+      phase: connection.phase,
+      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 {
+      kind: startupFailed ? "startup" : "connection",
+      phase: connection.phase,
+      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/connection.ts

@@ -1,5 +1,7 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 import { atom } from "jotai";
+import { atomWithReducer } from "jotai/utils";
+import type { NotificationMessageData } from "../kernel/messages";
 import { isNotebookPage } from "../mode";
 import { waitFor } from "../state/jotai";
 import { type ConnectionStatus, WebSocketState } from "../websocket/types";
@@ -12,6 +14,23 @@ export const connectionAtom = atom<ConnectionStatus>({
   state: WebSocketState.NOT_STARTED,
 });
 
+type StartupProgress = NotificationMessageData<"startup-progress">;
+
+export const startupProgressAtom = atomWithReducer<
+  Pick<StartupProgress, "phase" | "logs"> | null,
+  StartupProgress | null
+>(null, (previous, update: StartupProgress | null) =>
+  update === null
+    ? null
+    : {
+        phase: update.phase,
+        logs:
+          update.log_mode === "append" && previous?.phase === update.phase
+            ? previous.logs + update.logs
+            : update.logs,
+      },
+);
+
 export function waitForConnectionOpen() {
   return waitFor(connectionAtom, (value) => {
     return value.state === WebSocketState.OPEN;

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

@@ -0,0 +1,53 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { useAtomValue } from "jotai";
+import { useEffect, useState } from "react";
+import { useDelayElapsed } from "@/hooks/useDelayElapsed";
+import { isConnectedAtom } from "./connection";
+import {
+  type ConnectionNotice,
+  connectionNoticeAtom,
+} from "./connection-notice";
+
+export type DisplayConnectionNotice = ConnectionNotice & { ready: boolean };
+
+/** Briefly acknowledge completion, but only for setup the user actually saw. */
+export function useConnectionNotice(
+  delayMs = 500,
+): DisplayConnectionNotice | null {
+  const notice = useAtomValue(connectionNoticeAtom);
+  const connected = useAtomValue(isConnectedAtom);
+  const elapsed = useDelayElapsed(notice?.pending ? delayMs : 0);
+  const [previous, setPrevious] = useState<ConnectionNotice | null>(null);
+
+  useEffect(() => {
+    if (notice || !connected) {
+      setPrevious(elapsed ? notice : null);
+      return;
+    }
+    const timeout = setTimeout(() => setPrevious(null), 1500);
+    return () => clearTimeout(timeout);
+  }, [notice, connected, elapsed]);
+
+  if (notice) {
+    return elapsed ? { ...notice, ready: false } : null;
+  }
+  if (
+    connected &&
+    previous?.pending &&
+    previous.sandbox &&
+    previous.kind !== "connection"
+  ) {
+    return {
+      ...previous,
+      pending: false,
+      ready: true,
+      title:
+        previous.kind === "sync"
+          ? "Environment synced"
+          : "Your notebook is ready",
+      description: "The notebook is ready to run.",
+      error: null,
+    };
+  }
+  return null;
+}