@marimo-team/islands 0.25.3-dev6 → 0.25.3-dev61

package/src/components/editor/file-tree/use-file-search.ts

@@ -1,6 +1,6 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useRequestClient } from "@/core/network/requests";
 import { useDebounce } from "@/hooks/useDebounce";
 import {
@@ -34,20 +34,29 @@ export function useFileSearch({
 }): { state: FileSearchState; refetch: () => void } {
   const { sendSearchFiles } = useRequestClient();
   const debouncedQuery = useDebounce(query, 300);
-  const pending = useRef<Promise<void>>(Promise.resolve());
+  // Nullable so the ref is not built on every render
+  const pending = useRef<Promise<void> | null>(null);
   const [revision, setRevision] = useState(0);
   const refetch = useCallback(() => setRevision((value) => value + 1), []);
-  const [result, setResult] = useState<FileSearchState>({ status: "idle" });
+  const requestIdentity = useMemo(
+    () => ({ query, tree, showHiddenFiles, revision, sendSearchFiles }),
+    [query, tree, showHiddenFiles, revision, sendSearchFiles],
+  );
+  const [result, setResult] = useState<{
+    requestIdentity: typeof requestIdentity;
+    state: FileSearchState;
+  }>();
 
   useEffect(() => {
+    // Read inputs through requestIdentity so it alone drives new requests
+    const { query, tree, showHiddenFiles, sendSearchFiles } = requestIdentity;
     let cancelled = false;
     if (!query || query !== debouncedQuery) {
       return;
     }
-    setResult({ status: "loading", query });
     // Let the in-flight server scan finish before starting another. Superseded
     // queued queries and remaining roots are skipped, keeping scan work bounded.
-    const request = pending.current.then(async () => {
+    const request = (pending.current ?? Promise.resolve()).then(async () => {
       const filesByPath = new Map<string, FileTreeNode>();
       let rootLimitReached = false;
       let failedRootCount = 0;
@@ -88,9 +97,12 @@ export function useFileSearch({
       if (!cancelled) {
         if (roots.length > 0 && failedRootCount === roots.length) {
           setResult({
-            status: "error",
-            query,
-            error: new Error("Could not search any root"),
+            requestIdentity,
+            state: {
+              status: "error",
+              query,
+              error: new Error("Could not search any root"),
+            },
           });
           return;
         }
@@ -110,33 +122,35 @@ export function useFileSearch({
             rank(left) - rank(right) || left.name.localeCompare(right.name),
         );
         setResult({
-          status: "success",
-          isPartial: failedRootCount > 0,
-          query,
-          files: sortedFiles.slice(0, RESULT_LIMIT),
-          hasMore: rootLimitReached || sortedFiles.length > RESULT_LIMIT,
+          requestIdentity,
+          state: {
+            status: "success",
+            isPartial: failedRootCount > 0,
+            query,
+            files: sortedFiles.slice(0, RESULT_LIMIT),
+            hasMore: rootLimitReached || sortedFiles.length > RESULT_LIMIT,
+          },
         });
       }
     });
     pending.current = request.catch((error: unknown) => {
       if (!cancelled) {
-        setResult({ status: "error", query, error });
+        setResult({
+          requestIdentity,
+          state: { status: "error", query, error },
+        });
       }
     });
     return () => {
       cancelled = true;
     };
-  }, [query, debouncedQuery, tree, showHiddenFiles, revision, sendSearchFiles]);
+  }, [debouncedQuery, requestIdentity]);
 
   if (!query) {
     return { state: { status: "idle" }, refetch };
   }
-  if (
-    query !== debouncedQuery ||
-    result.status === "idle" ||
-    result.query !== query
-  ) {
+  if (query !== debouncedQuery || result?.requestIdentity !== requestIdentity) {
     return { state: { status: "loading", query }, refetch };
   }
-  return { state: result, refetch };
+  return { state: result.state, refetch };
 }

package/src/components/editor/output/MarimoTracebackOutput.tsx

@@ -248,7 +248,7 @@ export const replaceTracebackFilenames = (domNode: DOMNode) => {
             <Tooltip content={tooltipContent}>
               <button
                 type="button"
-                className="ml-1 p-1 rounded-sm hover:bg-muted transition-all inline"
+                className="ml-1 p-1 rounded-sm hover:bg-muted transition-colors inline"
               >
                 <BugPlayIcon
                   onClick={() => {

package/src/components/editor/output/console/ConsoleOutput.tsx

@@ -6,7 +6,7 @@ import {
   ChevronsUpDownIcon,
   WrapTextIcon,
 } from "lucide-react";
-import React, { useEffect, useLayoutEffect, useRef, useState } from "react";
+import React, { useEffect, useLayoutEffect, useState } from "react";
 import { ToggleButton } from "react-aria-components";
 import { DebuggerControls } from "@/components/debugger/debugger-code";
 import { CopyClipboardIcon } from "@/components/icons/copy-icon";
@@ -49,31 +49,21 @@ export const CONSOLE_CLEAR_DEBOUNCE_MS = 200;
  */
 function useDebouncedConsoleOutputs<T>(outputs: T[]): T[] {
   const [debouncedOutputs, setDebouncedOutputs] = useState(outputs);
-  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-  // Non-empty outputs: apply immediately and cancel any pending clear
+  // Non-empty outputs: apply immediately. Effect cleanup cancels pending clears.
   if (outputs.length > 0 && debouncedOutputs !== outputs) {
-    if (timerRef.current !== null) {
-      clearTimeout(timerRef.current);
-      timerRef.current = null;
-    }
     setDebouncedOutputs(outputs);
   }
 
   // Empty outputs: delay the clear so new outputs can arrive first
   useEffect(() => {
-    if (outputs.length === 0 && timerRef.current === null) {
-      timerRef.current = setTimeout(() => {
-        timerRef.current = null;
-        setDebouncedOutputs([]);
-      }, CONSOLE_CLEAR_DEBOUNCE_MS);
+    if (outputs.length > 0) {
+      return;
     }
-    return () => {
-      if (timerRef.current !== null) {
-        clearTimeout(timerRef.current);
-        timerRef.current = null;
-      }
-    };
+    const timer = setTimeout(() => {
+      setDebouncedOutputs([]);
+    }, CONSOLE_CLEAR_DEBOUNCE_MS);
+    return () => clearTimeout(timer);
   }, [outputs]);
 
   return debouncedOutputs;

package/src/components/icons/__tests__/large-spinner.test.tsx

@@ -0,0 +1,39 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { act, render, screen } from "@testing-library/react";
+import { Profiler } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { LargeSpinner } from "../large-spinner";
+
+describe("LargeSpinner", () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+
+  it("fades the old title without a second commit before the timer fires", () => {
+    const onRender = vi.fn();
+    const spinner = (title: string) => (
+      <Profiler id="spinner" onRender={onRender}>
+        <LargeSpinner title={title} />
+      </Profiler>
+    );
+    const { rerender } = render(spinner("Starting"));
+    onRender.mockClear();
+
+    rerender(spinner("Loading"));
+    expect(onRender).toHaveBeenCalledOnce();
+    expect(screen.getByText("Starting")).toHaveClass("opacity-0");
+
+    act(() => vi.advanceTimersByTime(300));
+    expect(screen.getByText("Loading")).toHaveClass("opacity-100");
+  });
+
+  it("restores visibility if the title changes back during the fade", () => {
+    const { rerender } = render(<LargeSpinner title="Starting" />);
+    rerender(<LargeSpinner title="Loading" />);
+    rerender(<LargeSpinner title="Starting" />);
+
+    expect(screen.getByText("Starting")).toHaveClass("opacity-100");
+    act(() => vi.advanceTimersByTime(300));
+    expect(screen.queryByText("Loading")).not.toBeInTheDocument();
+  });
+});

package/src/components/icons/large-spinner.tsx

@@ -1,23 +1,12 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
 import { Loader2Icon } from "lucide-react";
-import { useEffect, useState } from "react";
+import { useDebounce } from "@/hooks/useDebounce";
 import { cn } from "@/utils/cn";
 
 export const LargeSpinner = ({ title }: { title?: string }) => {
-  const [currentTitle, setCurrentTitle] = useState(title);
-  const [isVisible, setIsVisible] = useState(true);
-
-  useEffect(() => {
-    if (title !== currentTitle) {
-      setIsVisible(false);
-      const timer = setTimeout(() => {
-        setCurrentTitle(title);
-        setIsVisible(true);
-      }, 300); // Wait for fade out animation to complete
-      return () => clearTimeout(timer);
-    }
-  }, [title, currentTitle]);
+  const currentTitle = useDebounce(title, 300);
+  const isVisible = title === currentTitle;
 
   return (
     <div className="flex flex-col h-full flex-1 items-center justify-center p-4">

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

@@ -514,7 +514,7 @@ const MarimoFileComponent = ({ file }: { file: MarimoFile }) => {
 
   return (
     <a
-      className="py-1.5 px-4 hover:bg-(--blue-2) hover:text-primary transition-all duration-300 cursor-pointer group relative flex gap-4 items-center"
+      className="py-1.5 px-4 hover:bg-(--blue-2) hover:text-primary transition-colors duration-300 cursor-pointer group relative flex gap-4 items-center"
       key={file.path}
       href={href.toString()}
       target={tabTarget(file.initializationId || file.path)}
@@ -542,7 +542,7 @@ const MarimoFileComponent = ({ file }: { file: MarimoFile }) => {
           </div>
           <ExternalLinkIcon
             size={20}
-            className="group-hover:opacity-100 opacity-0 transition-all duration-300 text-primary"
+            className="group-hover:opacity-100 opacity-0 transition-opacity duration-300 text-primary"
           />
         </div>
         {!!file.lastModified && (
@@ -617,14 +617,14 @@ const CreateNewNotebook: React.FC = () => {
     <a
       className="relative rounded-lg p-6 group
       text-primary hover:bg-(--blue-2) shadow-md-solid shadow-accent border bg-(--blue-1)
-      transition-all duration-300 cursor-pointer
+      transition-colors duration-300 cursor-pointer
       "
       href={url}
       target="_blank"
       rel="noreferrer"
     >
       <h2 className="text-lg font-semibold">Create a new notebook</h2>
-      <div className="group-hover:opacity-100 opacity-0 absolute right-5 top-0 bottom-0 rounded-lg flex items-center justify-center transition-all duration-300">
+      <div className="group-hover:opacity-100 opacity-0 absolute right-5 top-0 bottom-0 rounded-lg flex items-center justify-center transition-opacity duration-300">
         <ExternalLinkIcon size={24} />
       </div>
     </a>

package/src/components/slides/slide-cell-view.tsx

@@ -117,7 +117,7 @@ export const SlideCellView = ({ cell }: { cell: RuntimeCell }) => {
       />
       <LanguageToggles
         code={cell.code}
-        editorView={editorViewRef.current}
+        editorViewRef={editorViewRef}
         currentLanguageAdapter={languageAdapter}
         onAfterToggle={afterToggleLanguage}
         className="flex items-center gap-1"

package/src/components/tracing/tracing.tsx

@@ -145,11 +145,11 @@ const TraceBlock: React.FC<{
   isMostRecentRun: boolean;
   chartPosition: ChartPosition;
   theme: ResolvedTheme;
-}> = ({ run, isMostRecentRun, chartPosition, isExpanded, theme }) => {
+}> = ({ run, isMostRecentRun, chartPosition, isExpanded: expanded, theme }) => {
   const setExpandedRuns = useSetAtom(expandedRunsAtom);
   // We prefer the user's last click, but if they haven't clicked on this run,
   // we expand the most recent run by default, otherwise we collapse it.
-  isExpanded = isExpanded ?? isMostRecentRun;
+  const isExpanded = expanded ?? isMostRecentRun;
 
   const onToggleExpanded = () => {
     setExpandedRuns((prev) => {

package/src/core/attachments/state.ts

@@ -1,17 +1,14 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
-import type { components } from "@marimo-team/marimo-api";
 import { atom } from "jotai";
-import { isConnectedAtom } from "@/core/network/connection";
+import type { Attachment } from "@marimo-team/client/protocol";
+import { notebookClientAtom } from "@/core/websocket/state";
 
-export type Attachment = components["schemas"]["Attachment"];
+export type { Attachment } from "@marimo-team/client/protocol";
 
-export const attachmentsAtom = atom<Attachment[]>([]);
 export const agentAttachmentsAtom = atom((get) => {
-  if (!get(isConnectedAtom)) {
-    return [];
-  }
-  return get(attachmentsAtom).filter(
+  const notebook = get(notebookClientAtom);
+  return (notebook ? get(notebook.attachmentsAtom) : []).filter(
     (attachment) => attachment.kind === "agent",
   );
 });

package/src/core/cells/__tests__/notebook-outline.test.ts

@@ -0,0 +1,113 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { createStore } from "jotai";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { MockNotebook } from "@/__mocks__/notebook";
+import { cellId } from "@/__tests__/branded";
+import {
+  createNotebookActions,
+  notebookAtom,
+  notebookOutline,
+  notebookReducer,
+} from "../cells";
+import { exportedForTesting } from "../document-changes";
+import type { Outline } from "../outline";
+
+const first = cellId("first");
+const second = cellId("second");
+const firstOutline: Outline = {
+  items: [{ name: "First", level: 1, by: { id: "first" } }],
+};
+const secondOutline: Outline = {
+  items: [{ name: "Second", level: 2, by: { id: "second" } }],
+};
+
+function setup() {
+  const store = createStore();
+  store.set(
+    notebookAtom,
+    MockNotebook.notebookState({
+      cellData: { [first]: { code: "x = 1" }, [second]: {} },
+      cellRuntime: {
+        [first]: { outline: firstOutline },
+        [second]: { outline: secondOutline },
+      },
+    }),
+  );
+  const actions = createNotebookActions((action) =>
+    store.set(notebookAtom, (state) => notebookReducer(state, action)),
+  );
+  return { store, actions };
+}
+
+afterEach(() => {
+  exportedForTesting.cancelPendingChanges();
+});
+
+describe("notebookOutline", () => {
+  it("does not notify outline subscribers when cell code changes", () => {
+    const { store, actions } = setup();
+    const initial = store.get(notebookOutline);
+    const listener = vi.fn();
+    const unsubscribe = store.sub(notebookOutline, listener);
+
+    actions.updateCellCode({
+      cellId: first,
+      code: "x = 2",
+      formattingChange: false,
+    });
+
+    expect(store.get(notebookOutline)).toBe(initial);
+    expect(listener).not.toHaveBeenCalled();
+    unsubscribe();
+  });
+
+  it("updates headings when runtime outlines change or are removed", () => {
+    const { store } = setup();
+    const updated: Outline = {
+      items: [{ name: "Updated", level: 1, by: { id: "updated" } }],
+    };
+
+    for (const outline of [updated, null]) {
+      store.set(notebookAtom, (state) => ({
+        ...state,
+        cellRuntime: {
+          ...state.cellRuntime,
+          [first]: { ...state.cellRuntime[first], outline },
+        },
+      }));
+      expect(store.get(notebookOutline)).toEqual({
+        items: [...(outline?.items ?? []), ...secondOutline.items],
+      });
+    }
+  });
+
+  it("keeps headings in cell order after moving and deleting cells", () => {
+    const { store, actions } = setup();
+    actions.moveCell({ cellId: second, before: true });
+    expect(store.get(notebookOutline)).toEqual({
+      items: [...secondOutline.items, ...firstOutline.items],
+    });
+
+    actions.deleteCell({ cellId: second });
+    expect(store.get(notebookOutline)).toEqual(firstOutline);
+  });
+
+  it("notifies subscribers when output is replaced with the same headings", () => {
+    const { store } = setup();
+    const listener = vi.fn();
+    const unsubscribe = store.sub(notebookOutline, listener);
+
+    store.set(notebookAtom, (state) => ({
+      ...state,
+      cellRuntime: {
+        ...state.cellRuntime,
+        [first]: { ...state.cellRuntime[first], outline: { ...firstOutline } },
+      },
+    }));
+
+    // Consumers must reconnect to replacement heading elements in the DOM.
+    expect(listener).toHaveBeenCalledOnce();
+    unsubscribe();
+  });
+});

package/src/core/cells/cells.ts

@@ -1761,7 +1761,8 @@ export const cellErrorsAtom = atom((get) => {
 });
 
 export const notebookOutline = atom((get) => {
-  const { cellIds, cellRuntime } = get(notebookAtom);
+  const cellIds = get(cellIdsAtom);
+  const cellRuntime = get(cellsRuntimeAtom);
   const outlines = cellIds.inOrderIds.map(
     (cellId) => cellRuntime[cellId].outline,
   );

package/src/core/cells/pending-delete-service.ts

@@ -134,12 +134,8 @@ export function usePendingDeleteService() {
       submit({ cellIds, deleteCell, deleteManyCells, store });
     },
     clear,
-    get idle() {
-      return entries.size === 0;
-    },
-    get shouldConfirmDelete() {
-      return entries.size > 1;
-    },
+    idle: entries.size === 0,
+    shouldConfirmDelete: entries.size > 1,
   };
 }
 

package/src/core/datasets/__tests__/data-source-discovery.test.ts

@@ -185,8 +185,8 @@ describe("isDetectedSourceConnected", () => {
   });
   const emptySnapshot = {
     dialects: [] as string[],
-    storageProtocols: [] as string[],
-    storageBackendTypes: [] as string[],
+    storageProtocols: new Set<string>(),
+    storageBackendTypes: new Set<string>(),
   };
 
   it("does not hide a source when nothing is connected", () => {
@@ -242,7 +242,7 @@ describe("isDetectedSourceConnected", () => {
     expect(
       isDetectedSourceConnected(s3, {
         ...emptySnapshot,
-        storageProtocols: ["s3"],
+        storageProtocols: new Set(["s3"]),
       }),
     ).toBe(true);
   });
@@ -262,7 +262,7 @@ describe("isDetectedSourceConnected", () => {
     expect(
       isDetectedSourceConnected(hf, {
         ...emptySnapshot,
-        storageBackendTypes: ["huggingface"],
+        storageBackendTypes: new Set(["huggingface"]),
       }),
     ).toBe(true);
   });

package/src/core/datasets/data-source-discovery.ts

@@ -27,8 +27,8 @@ export function matchesDiscoveryGroup(
  */
 export interface LiveConnectionSnapshot {
   dialects: readonly string[];
-  storageProtocols: readonly string[];
-  storageBackendTypes: readonly string[];
+  storageProtocols: ReadonlySet<string>;
+  storageBackendTypes: ReadonlySet<string>;
 }
 
 /**
@@ -47,15 +47,13 @@ export function isDetectedSourceConnected(
   }
 
   if (
-    match.protocols.some((protocol) =>
-      snapshot.storageProtocols.includes(protocol),
-    )
+    match.protocols.some((protocol) => snapshot.storageProtocols.has(protocol))
   ) {
     return true;
   }
 
   return match.backendTypes.some((backendType) =>
-    snapshot.storageBackendTypes.includes(backendType),
+    snapshot.storageBackendTypes.has(backendType),
   );
 }
 

package/src/core/edit-app.tsx

@@ -41,7 +41,7 @@ import { viewStateAtom } from "./mode";
 import { useRequestClient } from "./network/requests";
 import { useFilename } from "./saving/filename";
 import { lastSavedNotebookAtom } from "./saving/state";
-import { useMarimoKernelConnection } from "./websocket/useMarimoKernelConnection";
+import { useNotebookSession } from "./websocket/useNotebookSession";
 
 interface AppProps {
   /**
@@ -83,7 +83,7 @@ export const EditApp: React.FC<AppProps> = ({
     };
   }, []);
 
-  const { connection, reconnect } = useMarimoKernelConnection({
+  const { connection, reconnect } = useNotebookSession({
     autoInstantiate: userConfig.runtime.auto_instantiate,
     setCells: (cells, layout) => {
       setCells(cells);

package/src/core/host/AGENTS.md

@@ -1,6 +1,15 @@
 # Host core
 
-Production code may import host modules, `jotai/vanilla`, `zod`, and
-`@/utils/Logger`. Enforced by `marimo/host-imports`. Tests are exempt.
+Production code may import host modules, `@marimo-team/client`,
+`jotai/vanilla`, `zod`, and `@/utils/Logger`. Enforced by
+`marimo/host-imports`. Tests are exempt.
+
+The protocol schemas and types live in `@marimo-team/client/protocol`.
+The native `marimo` event is a marimo extension and is defined in `events.ts`.
 
 Define interfaces here and inject application behavior through adapters.
+
+`stream.ts` reduces stream events into one state. Each kind of object is a
+`Resource` in `resources/` with pure handlers keyed by event name. The stream
+handles phase, notebook identity, and control events itself. The client holds
+one state atom and exposes derived atoms.

package/src/core/host/__tests__/attachments.test.ts

@@ -0,0 +1,56 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { describe, expect, it } from "vitest";
+import { attachments } from "../resources/attachments";
+import { createReducer } from "@marimo-team/client/reducer";
+import { fixtureEvents } from "./fixtures";
+
+const reducer = createReducer({ attachments });
+const snapshot = fixtureEvents("notebook-events.sse");
+const records = snapshot.flatMap((event) =>
+  event.event === "attachment" ? [event.data.attachment] : [],
+);
+const confirmed = () => snapshot.reduce(reducer.reduce, reducer.initial);
+
+describe("attachment resource", () => {
+  it("collects snapshot records, replaces by id, and removes attachments", () => {
+    const state = confirmed();
+    expect(state.resources.attachments).toEqual(records);
+    const [browser, agent] = records;
+    const renamed = { ...agent, name: "Renamed agent" };
+    const updated = reducer.reduce(state, {
+      event: "attachment",
+      id: "98",
+      data: { attachment: renamed },
+    });
+    expect(updated.resources.attachments).toEqual([browser, renamed]);
+    expect(state.resources.attachments).toEqual(records);
+
+    const removed = reducer.reduce(updated, {
+      event: "attachment.removed",
+      id: "99",
+      data: { id: browser.id, time: "2026-10-01T09:30:00Z" },
+    });
+    expect(removed.resources.attachments).toEqual([renamed]);
+    const repeated = reducer.reduce(removed, {
+      event: "attachment.removed",
+      id: "100",
+      data: { id: browser.id, time: "2026-10-01T09:30:00Z" },
+    });
+    expect(repeated.resources.attachments).toBe(removed.resources.attachments);
+  });
+
+  it("rebuilds records after reset", () => {
+    const state = confirmed();
+    const reset = reducer.reduce(state, { event: "reset", data: {} });
+    expect(reset.resources.attachments).toEqual([]);
+    const replacement = snapshot
+      .filter(
+        (event) =>
+          event.event !== "attachment" ||
+          event.data.attachment.id === records[0].id,
+      )
+      .reduce(reducer.reduce, reset);
+    expect(replacement.resources.attachments).toEqual([records[0]]);
+  });
+});