@marimo-team/islands 0.23.10-dev22 → 0.23.10-dev23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marimo-team/islands",
-  "version": "0.23.10-dev22",
+  "version": "0.23.10-dev23",
   "main": "dist/main.js",
   "types": "dist/index.d.ts",
   "type": "module",

package/src/components/editor/chrome/wrapper/app-chrome.tsx

@@ -34,6 +34,26 @@ import { ErrorBoundary } from "../../boundary/ErrorBoundary";
 import { raf2 } from "../../navigation/focus-utils";
 import { ContextAwarePanel } from "../panels/context-aware-panel/context-aware-panel";
 import { PanelSectionProvider } from "../panels/panel-context";
+import { useTheme } from "@/theme/useTheme";
+import {
+  LazyAgentPanel,
+  LazyCachePanel,
+  LazyChatPanel,
+  LazyDependencyGraphPanel,
+  LazyDocumentationPanel,
+  LazyErrorsPanel,
+  LazyFileExplorerPanel,
+  LazyLogsPanel,
+  LazyOutlinePanel,
+  LazyPackagesPanel,
+  LazyScratchpadPanel,
+  LazySecretsPanel,
+  LazySessionPanel,
+  LazySnippetsPanel,
+  LazyTerminal,
+  LazyTracingPanel,
+  PANEL_PRELOADERS,
+} from "./lazy-panels";
 import { panelLayoutAtom, useChromeActions, useChromeState } from "../state";
 import {
   isPanelHidden,
@@ -50,33 +70,26 @@ import { useAiPanelTab } from "./useAiPanel";
 import { useDependencyPanelTab } from "./useDependencyPanelTab";
 import { handleDragging } from "./utils";
 
-const LazyTerminal = React.lazy(() => import("@/components/terminal/terminal"));
-const LazyChatPanel = React.lazy(() => import("@/components/chat/chat-panel"));
-const LazyAgentPanel = React.lazy(
-  () => import("@/components/chat/acp/agent-panel"),
-);
-const LazyDependencyGraphPanel = React.lazy(
-  () => import("@/components/editor/chrome/panels/dependency-graph-panel"),
-);
-const LazySessionPanel = React.lazy(() => import("../panels/session-panel"));
-const LazyDocumentationPanel = React.lazy(
-  () => import("../panels/documentation-panel"),
-);
-const LazyErrorsPanel = React.lazy(() => import("../panels/error-panel"));
-const LazyFileExplorerPanel = React.lazy(
-  () => import("../panels/file-explorer-panel"),
-);
-const LazyLogsPanel = React.lazy(() => import("../panels/logs-panel"));
-const LazyOutlinePanel = React.lazy(() => import("../panels/outline-panel"));
-const LazyPackagesPanel = React.lazy(() => import("../panels/packages-panel"));
-const LazyScratchpadPanel = React.lazy(
-  () => import("../panels/scratchpad-panel"),
-);
-const LazySecretsPanel = React.lazy(() => import("../panels/secrets-panel"));
-const LazySnippetsPanel = React.lazy(() => import("../panels/snippets-panel"));
-const LazyTracingPanel = React.lazy(() => import("../panels/tracing-panel"));
-const LazyCachePanel = React.lazy(() => import("../panels/cache-panel"));
-
+// Placeholder that matches the eventual xterm theme background so the
+// transition into the loaded terminal is seamless rather than a blank flash.
+const TerminalSkeleton: React.FC = () => {
+  const { theme } = useTheme();
+  const isDark = theme === "dark";
+  return (
+    <div
+      aria-label="Loading terminal"
+      role="status"
+      className="w-full h-full flex items-start p-3 font-mono text-xs select-none"
+      style={{
+        background: isDark ? "#0f172a" : "#ffffff",
+        color: isDark ? "#94a3b8" : "#64748b",
+      }}
+    >
+      <span className="opacity-70">Starting terminal</span>
+      <span className="ml-1 inline-block w-2 h-3.5 align-middle bg-current animate-pulse" />
+    </div>
+  );
+};
 export const AppChrome: React.FC<PropsWithChildren> = ({ children }) => {
   const {
     isSidebarOpen,
@@ -96,6 +109,33 @@ export const AppChrome: React.FC<PropsWithChildren> = ({ children }) => {
   const capabilities = useAtomValue(capabilitiesAtom);
   const aiEnabled = useAtomValue(aiEnabledAtom);
 
+  // On mount, idle-preload whichever panels the user had open at last unload,
+  // so the first interaction with the sidebar/dev panel doesn't hit a cold
+  // chunk fetch. Runs once.
+  // oxlint-disable-next-line react-hooks/exhaustive-deps
+  useEffect(() => {
+    const preloadOpenPanels = () => {
+      if (isSidebarOpen && selectedPanel) {
+        PANEL_PRELOADERS[selectedPanel]?.();
+      }
+      if (isDeveloperPanelOpen && selectedDeveloperPanelTab) {
+        PANEL_PRELOADERS[selectedDeveloperPanelTab]?.();
+      }
+    };
+
+    const canIdle =
+      typeof window !== "undefined" &&
+      typeof window.requestIdleCallback === "function";
+    if (canIdle) {
+      const handle = window.requestIdleCallback(preloadOpenPanels, {
+        timeout: 2000,
+      });
+      return () => window.cancelIdleCallback(handle);
+    }
+    const handle = setTimeout(preloadOpenPanels, 300);
+    return () => clearTimeout(handle);
+  }, []);
+
   // Convert current developer panel items to PanelDescriptors
   // Filter out hidden panels (e.g., terminal when capability is not available)
   const devPanelItems = useMemo(() => {
@@ -256,32 +296,34 @@ export const AppChrome: React.FC<PropsWithChildren> = ({ children }) => {
 
   const renderAiPanel = () => {
     if (agentsEnabled && aiPanelTab === "agents") {
-      return <LazyAgentPanel />;
+      return <LazyAgentPanel.Component />;
     }
-    return <LazyChatPanel />;
+    return <LazyChatPanel.Component />;
   };
 
   const SIDEBAR_PANELS: Record<PanelType, React.ReactNode> = {
-    files: <LazyFileExplorerPanel />,
-    variables: <LazySessionPanel />,
-    dependencies: <LazyDependencyGraphPanel />,
-    packages: <LazyPackagesPanel />,
-    outline: <LazyOutlinePanel />,
-    documentation: <LazyDocumentationPanel />,
-    snippets: <LazySnippetsPanel />,
+    files: <LazyFileExplorerPanel.Component />,
+    variables: <LazySessionPanel.Component />,
+    dependencies: <LazyDependencyGraphPanel.Component />,
+    packages: <LazyPackagesPanel.Component />,
+    outline: <LazyOutlinePanel.Component />,
+    documentation: <LazyDocumentationPanel.Component />,
+    snippets: <LazySnippetsPanel.Component />,
     ai: renderAiPanel(),
-    errors: <LazyErrorsPanel />,
-    scratchpad: <LazyScratchpadPanel />,
-    tracing: <LazyTracingPanel />,
-    secrets: <LazySecretsPanel />,
-    logs: <LazyLogsPanel />,
+    errors: <LazyErrorsPanel.Component />,
+    scratchpad: <LazyScratchpadPanel.Component />,
+    tracing: <LazyTracingPanel.Component />,
+    secrets: <LazySecretsPanel.Component />,
+    logs: <LazyLogsPanel.Component />,
     terminal: (
-      <LazyTerminal
-        visible={isSidebarOpen && selectedPanel === "terminal"}
-        onClose={() => setIsSidebarOpen(false)}
-      />
+      <Suspense fallback={<TerminalSkeleton />}>
+        <LazyTerminal.Component
+          visible={isSidebarOpen && selectedPanel === "terminal"}
+          onClose={() => setIsSidebarOpen(false)}
+        />
+      </Suspense>
     ),
-    cache: <LazyCachePanel />,
+    cache: <LazyCachePanel.Component />,
   };
 
   const helpPaneBody = (
@@ -414,12 +456,14 @@ export const AppChrome: React.FC<PropsWithChildren> = ({ children }) => {
   const DEVELOPER_PANELS: Record<PanelType, React.ReactNode> = {
     ...SIDEBAR_PANELS,
     terminal: (
-      <LazyTerminal
-        visible={
-          isDeveloperPanelOpen && selectedDeveloperPanelTab === "terminal"
-        }
-        onClose={() => setIsDeveloperPanelOpen(false)}
-      />
+      <Suspense fallback={<TerminalSkeleton />}>
+        <LazyTerminal.Component
+          visible={
+            isDeveloperPanelOpen && selectedDeveloperPanelTab === "terminal"
+          }
+          onClose={() => setIsDeveloperPanelOpen(false)}
+        />
+      </Suspense>
     ),
   };
 
@@ -474,6 +518,7 @@ export const AppChrome: React.FC<PropsWithChildren> = ({ children }) => {
             className="flex flex-row gap-1"
             minItems={0}
             onAction={(panel) => openApplication(panel.type)}
+            onItemPreloadHint={(panel) => PANEL_PRELOADERS[panel.type]?.()}
             renderItem={(panel) => (
               <div
                 className={cn(

package/src/components/editor/chrome/wrapper/lazy-panels.ts

@@ -0,0 +1,91 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { reactLazyWithPreload } from "@/utils/lazy";
+import { Logger } from "@/utils/Logger";
+import type { PanelType } from "../types";
+
+// Preloading is best-effort: a chunk-load failure here should not surface as
+// an unhandled rejection (the panel will retry the import when actually
+// rendered, where Suspense/ErrorBoundary handle the failure).
+const safePreload = (lazy: { preload: () => Promise<unknown> }) => (): void => {
+  void lazy.preload().catch((error) => {
+    Logger.debug("Failed to preload panel chunk", error);
+  });
+};
+
+// Centralized lazy panels. Using reactLazyWithPreload (instead of React.lazy)
+// gives each panel a .preload() method so the chunk can be fetched on intent
+// (hovering the sidebar icon or developer-panel tab) before the user clicks.
+
+export const LazyTerminal = reactLazyWithPreload(
+  () => import("@/components/terminal/terminal"),
+);
+export const LazyChatPanel = reactLazyWithPreload(
+  () => import("@/components/chat/chat-panel"),
+);
+export const LazyAgentPanel = reactLazyWithPreload(
+  () => import("@/components/chat/acp/agent-panel"),
+);
+export const LazyDependencyGraphPanel = reactLazyWithPreload(
+  () => import("../panels/dependency-graph-panel"),
+);
+export const LazySessionPanel = reactLazyWithPreload(
+  () => import("../panels/session-panel"),
+);
+export const LazyDocumentationPanel = reactLazyWithPreload(
+  () => import("../panels/documentation-panel"),
+);
+export const LazyErrorsPanel = reactLazyWithPreload(
+  () => import("../panels/error-panel"),
+);
+export const LazyFileExplorerPanel = reactLazyWithPreload(
+  () => import("../panels/file-explorer-panel"),
+);
+export const LazyLogsPanel = reactLazyWithPreload(
+  () => import("../panels/logs-panel"),
+);
+export const LazyOutlinePanel = reactLazyWithPreload(
+  () => import("../panels/outline-panel"),
+);
+export const LazyPackagesPanel = reactLazyWithPreload(
+  () => import("../panels/packages-panel"),
+);
+export const LazyScratchpadPanel = reactLazyWithPreload(
+  () => import("../panels/scratchpad-panel"),
+);
+export const LazySecretsPanel = reactLazyWithPreload(
+  () => import("../panels/secrets-panel"),
+);
+export const LazySnippetsPanel = reactLazyWithPreload(
+  () => import("../panels/snippets-panel"),
+);
+export const LazyTracingPanel = reactLazyWithPreload(
+  () => import("../panels/tracing-panel"),
+);
+export const LazyCachePanel = reactLazyWithPreload(
+  () => import("../panels/cache-panel"),
+);
+
+// Preloader registry: hovering an icon/tab calls into this map to warm the
+// corresponding chunk. Two panel types (chat and agents) share the "ai" slot,
+// so we preload both.
+export const PANEL_PRELOADERS: Record<PanelType, () => void> = {
+  files: safePreload(LazyFileExplorerPanel),
+  variables: safePreload(LazySessionPanel),
+  dependencies: safePreload(LazyDependencyGraphPanel),
+  packages: safePreload(LazyPackagesPanel),
+  outline: safePreload(LazyOutlinePanel),
+  documentation: safePreload(LazyDocumentationPanel),
+  snippets: safePreload(LazySnippetsPanel),
+  ai: () => {
+    safePreload(LazyChatPanel)();
+    safePreload(LazyAgentPanel)();
+  },
+  errors: safePreload(LazyErrorsPanel),
+  scratchpad: safePreload(LazyScratchpadPanel),
+  tracing: safePreload(LazyTracingPanel),
+  secrets: safePreload(LazySecretsPanel),
+  logs: safePreload(LazyLogsPanel),
+  terminal: safePreload(LazyTerminal),
+  cache: safePreload(LazyCachePanel),
+};

package/src/components/editor/chrome/wrapper/sidebar.tsx

@@ -22,6 +22,7 @@ import {
   PANELS,
   type PanelDescriptor,
 } from "../types";
+import { PANEL_PRELOADERS } from "./lazy-panels";
 
 export const Sidebar: React.FC = () => {
   const { selectedPanel, selectedDeveloperPanelTab, isSidebarOpen } =
@@ -141,6 +142,7 @@ export const Sidebar: React.FC = () => {
         className="flex flex-col gap-0"
         minItems={0}
         onAction={(panel) => toggleApplication(panel.type)}
+        onItemPreloadHint={(panel) => PANEL_PRELOADERS[panel.type]?.()}
         renderItem={(panel) => (
           <SidebarItem
             tooltip={panel.tooltip}

package/src/components/ui/reorderable-list.tsx

@@ -57,6 +57,12 @@ export interface ReorderableListProps<T> {
    * Callback when an item is clicked
    */
   onAction?: (item: T) => void;
+  /**
+   * Fired when an item is hovered or focused. Useful for preloading the
+   * resource the item points to before it is activated. Attached to the
+   * focusable list item so it works for both pointer and keyboard users.
+   */
+  onItemPreloadHint?: (item: T) => void;
   /**
    * All available items that can be added to the list
    */
@@ -142,6 +148,7 @@ export const ReorderableList = <T extends object>({
   ariaLabel = "Reorderable list",
   className,
   crossListDrag,
+  onItemPreloadHint,
 }: ReorderableListProps<T>) => {
   const mimeType = crossListDrag
     ? getDragMimeType(crossListDrag.dragType)
@@ -294,6 +301,12 @@ export const ReorderableList = <T extends object>({
           key={getKey(item)}
           id={getKey(item)}
           className="active:cursor-grabbing data-[dragging]:opacity-60 outline-none"
+          onHoverStart={
+            onItemPreloadHint ? () => onItemPreloadHint(item) : undefined
+          }
+          onFocus={
+            onItemPreloadHint ? () => onItemPreloadHint(item) : undefined
+          }
         >
           {renderItem(item)}
         </ListBoxItem>

package/src/utils/lazy.ts

@@ -3,7 +3,12 @@
 import React from "react";
 
 interface LazyComponentWithPreload<T> {
-  preload: () => void;
+  /**
+   * Eagerly trigger the dynamic import. Returns the import promise so callers
+   * can await it or attach error handling; safe to call multiple times (the
+   * import is memoized).
+   */
+  preload: () => Promise<{ default: React.ComponentType<T> }>;
   Component: React.LazyExoticComponent<React.ComponentType<T>>;
 }