@marimo-team/islands 0.23.14-dev2 → 0.23.14-dev21

package/src/core/runtime/adapter.ts

@@ -0,0 +1,182 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { type Atom, atom } from "jotai";
+import { kernelStateAtom } from "../kernel/state";
+import { islandsInitializedAtom } from "../islands/state";
+import { isIslands } from "../islands/utils";
+import { connectionAtom } from "../network/connection";
+import { isStaticNotebook } from "../static/static-state";
+import { wasmInitStateAtom } from "../wasm/state";
+import { isWasm } from "../wasm/utils";
+import { WebSocketState } from "../websocket/types";
+
+export type RuntimeKind = "wasm" | "remote" | "static" | "islands";
+
+export type AdapterState =
+  | { kind: "connecting"; progress?: { label: string; percent?: number } }
+  | { kind: "ready" }
+  | {
+      kind: "failed";
+      error: { message: string; errorKind: "init" | "runtime" };
+    };
+
+export interface RuntimeCapabilities {
+  canHealthCheck: boolean;
+  canShutdown: boolean;
+  canRestart: boolean;
+  supportsLsp: boolean;
+}
+
+/** Runtimes with no server-side kernel to manage (wasm, static, islands). */
+const NO_CAPABILITIES: RuntimeCapabilities = {
+  canHealthCheck: false,
+  canShutdown: false,
+  canRestart: false,
+  supportsLsp: false,
+};
+
+/**
+ * One adapter per runtime so consumers don't branch on `isWasm()` /
+ * `isStaticNotebook()` / `isIslands()` at the call site.
+ */
+export interface RuntimeAdapter {
+  readonly kind: RuntimeKind;
+  /** Short label suitable for status pills, e.g. "Kernel", "Pyodide". */
+  readonly label: string;
+  readonly capabilities: RuntimeCapabilities;
+  state: Atom<AdapterState>;
+}
+
+// --- WASM ------------------------------------------------------------------
+
+const wasmStateAtom = atom<AdapterState>((get) => {
+  const s = get(wasmInitStateAtom);
+  switch (s.kind) {
+    case "loading":
+      return { kind: "connecting", progress: { label: s.message } };
+    case "ready":
+      return { kind: "ready" };
+    case "error":
+      return {
+        kind: "failed",
+        error: { message: s.message, errorKind: "init" },
+      };
+  }
+});
+
+export const wasmAdapter: RuntimeAdapter = {
+  kind: "wasm",
+  label: "Pyodide",
+  capabilities: NO_CAPABILITIES,
+  state: wasmStateAtom,
+};
+
+// --- Remote ----------------------------------------------------------------
+
+const remoteStateAtom = atom<AdapterState>((get) => {
+  const conn = get(connectionAtom);
+  switch (conn.state) {
+    case WebSocketState.OPEN:
+      return { kind: "ready" };
+    case WebSocketState.CONNECTING:
+      return { kind: "connecting", progress: { label: "Connecting…" } };
+    case WebSocketState.NOT_STARTED:
+      return { kind: "connecting", progress: { label: "Not connected" } };
+    case WebSocketState.CLOSING:
+    case WebSocketState.CLOSED:
+      return {
+        kind: "failed",
+        error: {
+          message:
+            conn.state === WebSocketState.CLOSED
+              ? conn.reason
+              : "Disconnecting",
+          errorKind: "runtime",
+        },
+      };
+  }
+});
+
+export const remoteAdapter: RuntimeAdapter = {
+  kind: "remote",
+  label: "Kernel",
+  capabilities: {
+    canHealthCheck: true,
+    canShutdown: true,
+    canRestart: true,
+    supportsLsp: true,
+  },
+  state: remoteStateAtom,
+};
+
+// --- Static ----------------------------------------------------------------
+
+const staticStateAtom = atom<AdapterState>({ kind: "ready" });
+
+export const staticAdapter: RuntimeAdapter = {
+  kind: "static",
+  label: "Static",
+  capabilities: NO_CAPABILITIES,
+  state: staticStateAtom,
+};
+
+// --- Islands ---------------------------------------------------------------
+
+const islandsStateAtom = atom<AdapterState>((get) => {
+  const status = get(islandsInitializedAtom);
+  if (status === true) {
+    return { kind: "ready" };
+  }
+  if (typeof status === "string") {
+    return {
+      kind: "failed",
+      error: { message: status, errorKind: "init" },
+    };
+  }
+  return {
+    kind: "connecting",
+    progress: { label: "Initializing islands…" },
+  };
+});
+
+export const islandsAdapter: RuntimeAdapter = {
+  kind: "islands",
+  label: "Islands",
+  capabilities: NO_CAPABILITIES,
+  state: islandsStateAtom,
+};
+
+function selectAdapter(): RuntimeAdapter {
+  if (isStaticNotebook()) {
+    return staticAdapter;
+  }
+  if (isIslands()) {
+    return islandsAdapter;
+  }
+  if (isWasm()) {
+    return wasmAdapter;
+  }
+  return remoteAdapter;
+}
+
+/** Picked once at module load; the choice doesn't change after page load. */
+export const runtimeAdapterAtom = atom<RuntimeAdapter>(selectAdapter());
+
+/**
+ * Remote runtimes require both the WS to be open *and* the kernel to have
+ * ack'd instantiation. WASM/islands have no separate kernel handshake.
+ * Static notebooks never run cells.
+ */
+export const canRunCellsAtom = atom<boolean>((get) => {
+  const adapter = get(runtimeAdapterAtom);
+  if (get(adapter.state).kind !== "ready") {
+    return false;
+  }
+  if (adapter.kind === "static") {
+    return false;
+  }
+  if (adapter.kind === "remote") {
+    return get(kernelStateAtom).isInstantiated;
+  }
+  return true;
+});

package/src/core/wasm/PyodideLoader.tsx

@@ -5,54 +5,41 @@ import type React from "react";
 import type { PropsWithChildren } from "react";
 import { useEffect, useRef } from "react";
 import { LargeSpinner } from "@/components/icons/large-spinner";
+import { ProgressiveBoundary } from "@/components/lifecycle/ProgressiveBoundary";
 import { toast } from "@/components/ui/use-toast";
-import { hasCellsAtom } from "@/core/cells/cells";
-import { showCodeInRunModeAtom } from "@/core/meta/state";
-import { store } from "@/core/state/jotai";
+import { canPaintAtom } from "@/core/lifecycle/render-policy";
+import { wasmInitStateAtom } from "@/core/wasm/state";
 import { useAsyncData } from "@/hooks/useAsyncData";
 import { prettyError } from "@/utils/errors";
 import { Logger } from "@/utils/Logger";
-import { hasQueryParam } from "@/utils/urls";
-import { KnownQueryParams } from "../constants";
-import { type AppMode, getInitialAppMode } from "../mode";
 import { PyodideBridge } from "./bridge";
-import { hasAnyOutputAtom, wasmInitializationAtom } from "./state";
 import { isWasm } from "./utils";
 
 /**
- * HOC to load Pyodide before rendering children, if necessary.
+ * Paints the snapshot (or hydrated cells) immediately and lets Pyodide
+ * finish downloading in the background. UI elements aren't interactive
+ * until Pyodide is ready.
  */
 export const PyodideLoader: React.FC<PropsWithChildren> = ({ children }) => {
   if (!isWasm()) {
     return children;
   }
-
   return <PyodideLoaderInner>{children}</PyodideLoaderInner>;
 };
 
 const PyodideLoaderInner: React.FC<PropsWithChildren> = ({ children }) => {
-  // Don't block render on Pyodide: a hydrated snapshot can paint immediately
-  // while Pyodide downloads in the background.
   const { error } = useAsyncData(async () => {
     await PyodideBridge.INSTANCE.initialized.promise;
     return true;
   }, []);
 
-  const hasCells = useAtomValue(hasCellsAtom);
-  const hasOutput = useAtomValue(hasAnyOutputAtom);
-  const nothingToShow = shouldShowSpinner({
-    hasCells,
-    hasOutput,
-    mode: getInitialAppMode(),
-    codeHidden: isCodeHidden(),
-  });
+  const canPaint = useAtomValue(canPaintAtom);
 
+  // If the snapshot is already on screen, toast instead of throwing so we
+  // don't tear it down. With nothing painted, throw to surface the error UI.
   const didToastErrorRef = useRef(false);
   useEffect(() => {
-    // With snapshot content on-screen, toast instead of throwing so the
-    // snapshot stays readable. The ref ensures we only toast once even if
-    // nothingToShow toggles later.
-    if (error && !nothingToShow && !didToastErrorRef.current) {
+    if (error && canPaint && !didToastErrorRef.current) {
       didToastErrorRef.current = true;
       Logger.error("Pyodide failed to initialize", error);
       toast({
@@ -61,50 +48,21 @@ const PyodideLoaderInner: React.FC<PropsWithChildren> = ({ children }) => {
         variant: "danger",
       });
     }
-  }, [error, nothingToShow]);
+  }, [error, canPaint]);
 
-  if (error && nothingToShow) {
+  if (error && !canPaint) {
     throw error;
   }
 
-  if (nothingToShow) {
-    return <WasmSpinner />;
-  }
-
-  return children;
-};
-
-function isCodeHidden() {
-  // Code is hidden if ANY are true:
-  // - the query param is set to false
-  // - the view.showAppCode is false
   return (
-    hasQueryParam(KnownQueryParams.showCode, "false") ||
-    !store.get(showCodeInRunModeAtom)
+    <ProgressiveBoundary requires={canPaintAtom} fallback={<WasmSpinner />}>
+      {children}
+    </ProgressiveBoundary>
   );
-}
-
-/**
- * Pure predicate: should the WASM loader render a spinner instead of its
- * children? We block render only when nothing user-visible would appear:
- *   - no cells have been hydrated (Pyodide hasn't parsed the notebook), or
- *   - we are in headless run mode (code hidden) with no outputs to display.
- */
-export function shouldShowSpinner(input: {
-  hasCells: boolean;
-  hasOutput: boolean;
-  mode: AppMode;
-  codeHidden: boolean;
-}): boolean {
-  const { hasCells, hasOutput, mode, codeHidden } = input;
-  if (!hasCells) {
-    return true;
-  }
-  return !hasOutput && mode === "read" && codeHidden;
-}
-
-export const WasmSpinner: React.FC<PropsWithChildren> = ({ children }) => {
-  const wasmInitialization = useAtomValue(wasmInitializationAtom);
+};
 
-  return <LargeSpinner title={wasmInitialization} />;
+const WasmSpinner: React.FC = () => {
+  const state = useAtomValue(wasmInitStateAtom);
+  const title = state.kind === "loading" ? state.message : "Loading…";
+  return <LargeSpinner title={title} />;
 };

package/src/core/wasm/bridge.ts

@@ -38,7 +38,7 @@ import type { IConnectionTransport } from "../websocket/transports/transport";
 import { PyodideRouter } from "./router";
 import { getWorkerRPC } from "./rpc";
 import { createShareableLink } from "./share";
-import { wasmInitializationAtom, wasmInitStatusAtom } from "./state";
+import { wasmInitStateAtom } from "./state";
 import { fallbackFileStore, notebookFileStore } from "./store";
 import { isWasm } from "./utils";
 import type { SaveWorkerSchema } from "./worker/save-worker";
@@ -120,11 +120,16 @@ export class PyodideBridge implements RunRequests, EditRequests {
       // By initializing after, we get hits on cached network requests
       this.saveRpc = this.getSaveWorker();
       this.setInterruptBuffer();
-      store.set(wasmInitStatusAtom, "ready");
+      store.set(wasmInitStateAtom, { kind: "ready" });
       this.initialized.resolve();
     });
     this.rpc.addMessageListener("initializingMessage", ({ message }) => {
-      store.set(wasmInitializationAtom, message);
+      // Only bump the progress label while still loading — if we've already
+      // reached "ready" or "error", a late message shouldn't roll us back.
+      const current = store.get(wasmInitStateAtom);
+      if (current.kind === "loading") {
+        store.set(wasmInitStateAtom, { kind: "loading", message });
+      }
     });
     this.rpc.addMessageListener("initializedError", ({ error }) => {
       // If already initialized, surface as a toast and leave the deferred /
@@ -138,7 +143,7 @@ export class PyodideBridge implements RunRequests, EditRequests {
         });
         return;
       }
-      store.set(wasmInitStatusAtom, "error");
+      store.set(wasmInitStateAtom, { kind: "error", message: error });
       this.initialized.reject(new Error(error));
     });
     this.rpc.addMessageListener("kernelMessage", ({ message }) => {

package/src/core/wasm/state.ts

@@ -1,24 +1,13 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 import { atom } from "jotai";
-import { notebookAtom } from "../cells/cells";
-import { isOutputEmpty } from "../cells/outputs";
 
-export const wasmInitializationAtom = atom<string>("Initializing...");
+/** Tagged so the progress label and error message can't drift apart. */
+export type WasmInitState =
+  | { kind: "loading"; message: string }
+  | { kind: "ready" }
+  | { kind: "error"; message: string };
 
-export type WasmInitStatus = "loading" | "ready" | "error";
-export const wasmInitStatusAtom = atom<WasmInitStatus>("loading");
-
-export const hasAnyOutputAtom = atom<boolean>((get) => {
-  const notebook = get(notebookAtom);
-  const runtimeStates = Object.values(notebook.cellRuntime);
-  // First check if there is any output
-  const hasOutput = runtimeStates.some(
-    (runtime) => !isOutputEmpty(runtime.output),
-  );
-  if (hasOutput) {
-    return true;
-  }
-  // If there is no output, check if they have all run to completion
-  // in case this notebook doesn't contain outputs
-  return runtimeStates.every((runtime) => runtime.status === "idle");
+export const wasmInitStateAtom = atom<WasmInitState>({
+  kind: "loading",
+  message: "Initializing...",
 });

package/src/core/wasm/store.ts

@@ -62,7 +62,7 @@ const remoteDefaultFileStore: FileStore = {
     if (window.location.hostname !== "marimo.app") {
       return null;
     }
-    const url = new URL("files/wasm-intro.py", document.baseURI);
+    const url = new URL("export_demos/wasm-intro.py", document.baseURI);
     return fetch(url.toString())
       .then((res) => (res.ok ? res.text() : null))
       .catch(() => null);

package/src/hooks/__tests__/useDelayElapsed.test.tsx

@@ -0,0 +1,55 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useDelayElapsed } from "../useDelayElapsed";
+
+describe("useDelayElapsed", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("resolves true immediately when delay <= 0", () => {
+    const { result } = renderHook(() => useDelayElapsed(0));
+    expect(result.current).toBe(true);
+  });
+
+  it("stays false until the delay elapses, then flips true", () => {
+    const { result } = renderHook(() => useDelayElapsed(2000));
+    expect(result.current).toBe(false);
+
+    act(() => vi.advanceTimersByTime(1999));
+    expect(result.current).toBe(false);
+
+    act(() => vi.advanceTimersByTime(1));
+    expect(result.current).toBe(true);
+  });
+
+  it("restarts the timer when the delay changes", () => {
+    const { result, rerender } = renderHook(
+      ({ delay }) => useDelayElapsed(delay),
+      { initialProps: { delay: 1000 } },
+    );
+
+    act(() => vi.advanceTimersByTime(1000));
+    expect(result.current).toBe(true);
+
+    rerender({ delay: 500 });
+    expect(result.current).toBe(false);
+
+    act(() => vi.advanceTimersByTime(500));
+    expect(result.current).toBe(true);
+  });
+
+  it("clears the timer on unmount", () => {
+    const { unmount } = renderHook(() => useDelayElapsed(1000));
+    expect(vi.getTimerCount()).toBe(1);
+    unmount();
+    // The pending timeout must be cleared, not left dangling.
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});

package/src/hooks/useDelayElapsed.ts

@@ -0,0 +1,27 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { useLayoutEffect, useState } from "react";
+
+/**
+ * Returns `false` until `delayMs` has elapsed since mount (or since `delayMs`
+ * last changed), then `true`. Resolves to `true` immediately when
+ * `delayMs <= 0`. Useful for suppressing spinner/fallback flashes.
+ */
+export function useDelayElapsed(delayMs: number): boolean {
+  const [elapsed, setElapsed] = useState(delayMs <= 0);
+
+  // Layout effect (not a plain effect) so that when `delayMs` flips from `<= 0`
+  // to `> 0` — e.g. a gate re-closing — we reset `elapsed` to `false` before
+  // the browser paints, rather than briefly flashing the fallback for a frame.
+  useLayoutEffect(() => {
+    if (delayMs <= 0) {
+      setElapsed(true);
+      return;
+    }
+    setElapsed(false);
+    const timeout = setTimeout(() => setElapsed(true), delayMs);
+    return () => clearTimeout(timeout);
+  }, [delayMs]);
+
+  return elapsed;
+}

package/src/core/ai/context/providers/__tests__/__snapshots__/error.test.ts.snap

@@ -1,3 +0,0 @@
-// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
-
-exports[`ErrorContextProvider > formatContext > should format context for basic errors > basic-error-context 1`] = `"<error name="Cell 1" description="Invalid syntax"></error>"`;

package/src/core/wasm/__tests__/PyodideLoader.test.ts

@@ -1,72 +0,0 @@
-/* Copyright 2026 Marimo. All rights reserved. */
-
-import { describe, expect, it } from "vitest";
-import { shouldShowSpinner } from "../PyodideLoader";
-
-describe("shouldShowSpinner", () => {
-  it("shows the spinner when there are no cells yet (Pyodide hasn't parsed)", () => {
-    expect(
-      shouldShowSpinner({
-        hasCells: false,
-        hasOutput: false,
-        mode: "read",
-        codeHidden: false,
-      }),
-    ).toBe(true);
-
-    expect(
-      shouldShowSpinner({
-        hasCells: false,
-        hasOutput: true,
-        mode: "edit",
-        codeHidden: false,
-      }),
-    ).toBe(true);
-  });
-
-  it("renders children once cells exist with code visible", () => {
-    // run mode, code visible, no outputs yet — the user can read the code
-    expect(
-      shouldShowSpinner({
-        hasCells: true,
-        hasOutput: false,
-        mode: "read",
-        codeHidden: false,
-      }),
-    ).toBe(false);
-  });
-
-  it("renders children once cells exist with cached outputs (snapshot case)", () => {
-    expect(
-      shouldShowSpinner({
-        hasCells: true,
-        hasOutput: true,
-        mode: "read",
-        codeHidden: true,
-      }),
-    ).toBe(false);
-  });
-
-  it("keeps the spinner up in headless run mode with no outputs", () => {
-    // read mode + code hidden + no outputs = nothing visible to render
-    expect(
-      shouldShowSpinner({
-        hasCells: true,
-        hasOutput: false,
-        mode: "read",
-        codeHidden: true,
-      }),
-    ).toBe(true);
-  });
-
-  it("never blocks edit mode once cells exist", () => {
-    expect(
-      shouldShowSpinner({
-        hasCells: true,
-        hasOutput: false,
-        mode: "edit",
-        codeHidden: true,
-      }),
-    ).toBe(false);
-  });
-});

package/src/core/wasm/__tests__/state.test.ts

@@ -1,124 +0,0 @@
-/* Copyright 2026 Marimo. All rights reserved. */
-
-import { createRef } from "react";
-import { describe, expect, it } from "vitest";
-import { cellId } from "@/__tests__/branded";
-import type { NotebookState } from "@/core/cells/cells";
-import { initialNotebookState, notebookAtom } from "@/core/cells/cells";
-import { createCell, createCellRuntimeState } from "@/core/cells/types";
-import type { OutputMessage } from "@/core/kernel/messages";
-import { store } from "@/core/state/jotai";
-import { CollapsibleTree, MultiColumn } from "@/utils/id-tree";
-import { hasAnyOutputAtom } from "../state";
-
-describe("hasAnyOutputAtom", () => {
-  const createNotebookState = (
-    outputs: (OutputMessage | null)[],
-  ): NotebookState => ({
-    ...initialNotebookState(),
-    cellIds: new MultiColumn([
-      CollapsibleTree.from(outputs.map((_, i) => cellId(`${i}`))),
-    ]),
-    cellData: Object.fromEntries(
-      outputs.map((_, i) => [
-        cellId(`${i}`),
-        createCell({ id: cellId(`${i}`) }),
-      ]),
-    ),
-    cellRuntime: Object.fromEntries(
-      outputs.map((output, i) => [
-        `${i}`,
-        createCellRuntimeState({
-          output,
-          status: "queued",
-          outline: { items: [] },
-        }),
-      ]),
-    ),
-    cellHandles: Object.fromEntries(
-      outputs.map((_, i) => [cellId(`${i}`), createRef()]),
-    ),
-  });
-
-  it("should return false when there are no outputs", () => {
-    store.set(notebookAtom, createNotebookState([null, null]));
-    expect(store.get(hasAnyOutputAtom)).toBe(false);
-  });
-
-  it("should return false when all outputs are empty", () => {
-    store.set(
-      notebookAtom,
-      createNotebookState([
-        { channel: "output", mimetype: "text/plain", data: "", timestamp: 0 },
-        { channel: "output", mimetype: "text/plain", data: "", timestamp: 0 },
-      ]),
-    );
-    expect(store.get(hasAnyOutputAtom)).toBe(false);
-  });
-
-  it("should return true when there is at least one non-empty output", () => {
-    store.set(
-      notebookAtom,
-      createNotebookState([
-        { channel: "output", mimetype: "text/plain", data: "", timestamp: 0 },
-        {
-          channel: "output",
-          mimetype: "text/plain",
-          data: "hello",
-          timestamp: 0,
-        },
-      ]),
-    );
-    expect(store.get(hasAnyOutputAtom)).toBe(true);
-  });
-
-  it("should handle various output types", () => {
-    store.set(
-      notebookAtom,
-      createNotebookState([
-        {
-          channel: "output",
-          mimetype: "application/json",
-          data: { foo: "bar" },
-          timestamp: 0,
-        },
-        { channel: "output", mimetype: "text/plain", data: "", timestamp: 0 },
-      ]),
-    );
-    expect(store.get(hasAnyOutputAtom)).toBe(true);
-  });
-
-  it("should return true when all outputs are idle", () => {
-    const notebookState = createNotebookState([null, null]);
-    const cellId0 = cellId("0");
-    const cellId1 = cellId("1");
-    // Some idle cell, so returns false
-    store.set(notebookAtom, {
-      ...notebookState,
-      cellRuntime: {
-        ...notebookState.cellRuntime,
-        [cellId0]: {
-          ...notebookState.cellRuntime[cellId0],
-          status: "idle",
-        },
-      },
-    });
-    expect(store.get(hasAnyOutputAtom)).toBe(false);
-
-    // All cells are idle, so returns true
-    store.set(notebookAtom, {
-      ...notebookState,
-      cellRuntime: {
-        [cellId0]: {
-          ...notebookState.cellRuntime[cellId0],
-          status: "idle",
-        },
-        [cellId1]: {
-          ...notebookState.cellRuntime[cellId1],
-          status: "idle",
-        },
-      },
-    });
-    expect(store.get(hasAnyOutputAtom)).toBe(true);
-  });
-});