@marimo-team/islands 0.25.3-dev29 → 0.25.3-dev290

package/src/core/{host → notebook/replica}/resources/attachments.ts

@@ -1,10 +1,13 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
-import type { Attachment } from "../protocol";
-import type { Resource } from "./resource";
+import type { Attachment } from "@marimo-team/client/protocol";
+import type { NotebookResource } from "@marimo-team/client";
 
 /** Attachment records retained with the stream's resume cursor. */
-export const attachments: Resource<readonly Attachment[]> = {
+export const attachments: NotebookResource<
+  readonly Attachment[],
+  "attachment"
+> = {
   initial: [],
   on: {
     attachment: (state, { data: { attachment } }) =>

package/src/core/{host → notebook/replica}/resources/document.ts

@@ -1,7 +1,7 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
-import type * as Protocol from "../protocol";
-import type { Resource } from "./resource";
+import type * as Protocol from "@marimo-team/client/protocol";
+import type { NotebookResource } from "@marimo-team/client";
 
 /**
  * The notebook's content at one revision.
@@ -58,7 +58,7 @@ function publish(
   return { current: { revision, cells }, pending: null };
 }
 
-export const document: Resource<DocumentState> = {
+export const document: NotebookResource<DocumentState, "cell" | "document"> = {
   initial: { current: null, pending: null },
   on: {
     cell: (state, { data }) => {

package/src/core/notebook/replica/resources/executions.ts

@@ -0,0 +1,157 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type * as Protocol from "@marimo-team/client/protocol";
+import type { NotebookResource } from "@marimo-team/client";
+
+/** A console line, display, or input an execution produced, tagged by kind. */
+export type Item =
+  | (Protocol.Console & { readonly kind: "console" })
+  | (Protocol.Display & { readonly kind: "display" })
+  | (Protocol.Input & { readonly kind: "input" });
+
+/** An execution on the stream, with the items and variables it has produced. */
+export interface Execution {
+  readonly record: Protocol.Execution;
+  /** Items by id. `itemsInOrder` sorts them by `seq`. */
+  readonly items: ReadonlyMap<Protocol.ItemId, Item>;
+  /** The variables the execution bound, by item id. */
+  readonly variables: ReadonlyMap<Protocol.ItemId, Protocol.Variable>;
+}
+
+/**
+ * Runs and executions as the stream reports them.
+ *
+ * Nothing outlives its removal. The host removes a cell's previous
+ * execution before it publishes the next one, so `results` keeps each
+ * cell's last completed record for display.
+ */
+export interface Executions {
+  readonly runs: ReadonlyMap<Protocol.RunId, Protocol.Run>;
+  /** Every execution on the stream, scratch included. */
+  readonly executions: ReadonlyMap<Protocol.ExecutionId, Execution>;
+  /** The execution on the stream for each cell that has one. */
+  readonly latest: ReadonlyMap<Protocol.CellId, Protocol.ExecutionId>;
+}
+
+type Kind = "run" | "execution" | "console" | "display" | "input" | "variable";
+
+/** An execution's items in the order they were produced. */
+export function itemsInOrder(execution: Pick<Execution, "items">): Item[] {
+  return [...execution.items.values()].toSorted((a, b) => a.seq - b.seq);
+}
+
+function without<K, V>(map: ReadonlyMap<K, V>, key: K): ReadonlyMap<K, V> {
+  if (!map.has(key)) {
+    return map;
+  }
+  const next = new Map(map);
+  next.delete(key);
+  return next;
+}
+
+/** Replace an execution on the stream, indexed under its cell. */
+function set(state: Executions, execution: Execution): Executions {
+  const { id, cell_id: cellId } = execution.record;
+  return {
+    ...state,
+    executions: new Map(state.executions).set(id, execution),
+    latest:
+      cellId === null || state.latest.get(cellId) === id
+        ? state.latest
+        : new Map(state.latest).set(cellId, id),
+  };
+}
+
+function remove(state: Executions, id: Protocol.ExecutionId): Executions {
+  const execution = state.executions.get(id);
+  if (execution === undefined) {
+    return state;
+  }
+  const cellId = execution.record.cell_id;
+  return {
+    ...state,
+    executions: without(state.executions, id),
+    latest:
+      cellId !== null && state.latest.get(cellId) === id
+        ? without(state.latest, cellId)
+        : state.latest,
+  };
+}
+
+function attach(state: Executions, item: Item): Executions {
+  const execution = state.executions.get(item.execution_id);
+  if (execution === undefined) {
+    return state;
+  }
+  return set(state, {
+    ...execution,
+    items: new Map(execution.items).set(item.id, item),
+  });
+}
+
+function detach(state: Executions, itemId: Protocol.ItemId): Executions {
+  for (const execution of state.executions.values()) {
+    if (execution.items.has(itemId)) {
+      return set(state, {
+        ...execution,
+        items: without(execution.items, itemId),
+      });
+    }
+  }
+  return state;
+}
+
+function bind(state: Executions, variable: Protocol.Variable): Executions {
+  const execution = state.executions.get(variable.execution_id);
+  if (execution === undefined) {
+    return state;
+  }
+  return set(state, {
+    ...execution,
+    variables: new Map(execution.variables).set(variable.id, variable),
+  });
+}
+
+function unbind(state: Executions, itemId: Protocol.ItemId): Executions {
+  for (const execution of state.executions.values()) {
+    if (execution.variables.has(itemId)) {
+      return set(state, {
+        ...execution,
+        variables: without(execution.variables, itemId),
+      });
+    }
+  }
+  return state;
+}
+
+export const executions: NotebookResource<Executions, Kind> = {
+  initial: { runs: new Map(), executions: new Map(), latest: new Map() },
+  on: {
+    run: (state, { data }) => ({
+      ...state,
+      runs: new Map(state.runs).set(data.run.id, data.run),
+    }),
+    "run.removed": (state, { data }) =>
+      state.runs.has(data.id)
+        ? { ...state, runs: without(state.runs, data.id) }
+        : state,
+    execution: (state, { data: { execution: record } }) => {
+      const previous = state.executions.get(record.id);
+      return set(state, {
+        record,
+        items: previous?.items ?? new Map(),
+        variables: previous?.variables ?? new Map(),
+      });
+    },
+    "execution.removed": (state, { data }) => remove(state, data.id),
+    console: (state, { data }) =>
+      attach(state, { ...data.console, kind: "console" }),
+    "console.removed": (state, { data }) => detach(state, data.id),
+    display: (state, { data }) =>
+      attach(state, { ...data.display, kind: "display" }),
+    "display.removed": (state, { data }) => detach(state, data.id),
+    input: (state, { data }) => attach(state, { ...data.input, kind: "input" }),
+    variable: (state, { data }) => bind(state, data.variable),
+    "variable.removed": (state, { data }) => unbind(state, data.id),
+  },
+};

package/src/core/notebook/replica/resources/results.ts

@@ -0,0 +1,48 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type * as Protocol from "@marimo-team/client/protocol";
+import type { NotebookResource } from "@marimo-team/client";
+
+/**
+ * Each document cell's last completed execution record.
+ *
+ * The host removes a cell's previous execution before it publishes the
+ * next one. A result stays until a newer execution for the cell completes
+ * or the cell leaves the document, so a cell can show its last outcome
+ * while it runs again. Only the record is kept. Its outcome carries the
+ * cell's output, while items and variables stay with the stream's copy of
+ * the execution.
+ *
+ * A cell has an entry from its `cell` event until its removal, null until
+ * it completes once. Cells precede their executions on the stream, so a
+ * completion for a cell without an entry belongs to a cell the document
+ * no longer has.
+ */
+export type Results = ReadonlyMap<Protocol.CellId, Protocol.Execution | null>;
+
+export const results: NotebookResource<Results, "cell" | "execution"> = {
+  initial: new Map(),
+  on: {
+    cell: (state, { data }) =>
+      state.has(data.cell.id) ? state : new Map(state).set(data.cell.id, null),
+    "cell.removed": (state, { data }) => {
+      if (!state.has(data.id)) {
+        return state;
+      }
+      const next = new Map(state);
+      next.delete(data.id);
+      return next;
+    },
+    execution: (state, { data: { execution } }) => {
+      const cellId = execution.cell_id;
+      if (
+        cellId === null ||
+        execution.status !== "completed" ||
+        !state.has(cellId)
+      ) {
+        return state;
+      }
+      return new Map(state).set(cellId, execution);
+    },
+  },
+};

package/src/core/notebook/replica/resources/runtime.ts

@@ -0,0 +1,14 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type { Runtime } from "@marimo-team/client/protocol";
+import type { NotebookResource } from "@marimo-team/client";
+
+/** The notebook's runtime record while it has one. */
+export const runtime: NotebookResource<Runtime | null, "runtime"> = {
+  initial: null,
+  on: {
+    runtime: (_state, { data }) => data.runtime,
+    "runtime.removed": (state, { data }) =>
+      state !== null && state.id === data.id ? null : state,
+  },
+};

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

@@ -17,7 +17,7 @@ import type {
 } from "@/core/network/types";
 import { filenameAtom } from "@/core/saving/file-state";
 import { store } from "@/core/state/jotai";
-import { ConnectionState } from "@/core/websocket/types";
+import { ConnectionState } from "@/core/session/types";
 import { HTTPError } from "@/utils/errors";
 import { packageDataVersionAtom } from "../package-data";
 import {

package/src/core/packages/useSandboxController.ts

@@ -8,7 +8,7 @@ import { useRequestClient } from "@/core/network/requests";
 import { useFilename } from "@/core/saving/filename";
 import { waitFor } from "@/core/state/jotai";
 import { isWasm } from "@/core/wasm/utils";
-import { ConnectionState } from "@/core/websocket/types";
+import { ConnectionState } from "@/core/session/types";
 import { HTTPError, prettyError } from "@/utils/errors";
 import { invalidatePackageData } from "./package-data";
 import {

package/src/core/run-app.tsx

@@ -11,18 +11,16 @@ import { Spinner } from "@/components/icons/spinner";
 import { buttonVariants } from "@/components/ui/button";
 import { cn } from "@/utils/cn";
 import { CellsRenderer } from "../components/editor/renderers/cells-renderer";
-import {
-  hasCellsAtom,
-  notebookIsRunningAtom,
-  useCellActions,
-} from "./cells/cells";
+import { hasCellsAtom } from "./cells/cells";
+import { notebookIsRunningAtom } from "./executions";
 import type { AppConfig } from "./config/config-schema";
+import { DocumentProvider } from "./notebook/document";
 import { RuntimeState } from "./kernel/RuntimeState";
 import { getSessionId } from "./kernel/session";
 import { connectionAtom } from "./network/connection";
 import { useRequestClient } from "./network/requests";
-import { isAppConnecting } from "./websocket/connection-utils";
-import { useNotebookSession } from "./websocket/useNotebookSession";
+import { isAppConnecting } from "./session/connection-utils";
+import { useNotebookSession } from "./session/useNotebookSession";
 
 interface AppProps {
   appConfig: AppConfig;
@@ -40,7 +38,6 @@ const canPaintRunAppAtom = atom(
 );
 
 export const RunApp: React.FC<AppProps> = ({ appConfig, hideHeader }) => {
-  const { setCells } = useCellActions();
   const { sendComponentValues } = useRequestClient();
 
   // Initialize RuntimeState event-listeners
@@ -49,11 +46,10 @@ export const RunApp: React.FC<AppProps> = ({ appConfig, hideHeader }) => {
     return () => {
       RuntimeState.INSTANCE.stop();
     };
-  }, []);
+  }, [sendComponentValues]);
 
-  const { connection, reconnect } = useNotebookSession({
+  const { connection, reconnect, documentModel } = useNotebookSession({
     autoInstantiate: true,
-    setCells: setCells,
     sessionId: getSessionId(),
   });
 
@@ -73,47 +69,49 @@ export const RunApp: React.FC<AppProps> = ({ appConfig, hideHeader }) => {
   })();
 
   return (
-    <AppContainer
-      connection={connection}
-      isRunning={isRunning}
-      width={appConfig.width}
-      onReconnect={reconnect}
-    >
-      <KernelStartupErrorModal />
-      <AppHeader
+    <DocumentProvider model={documentModel}>
+      <AppContainer
         connection={connection}
-        className={hideHeader ? "hidden" : "sm:pt-8"}
+        isRunning={isRunning}
+        width={appConfig.width}
+        onReconnect={reconnect}
       >
-        {galleryHref && (
-          <div className="flex items-center px-6 pt-4 sm:-mt-8">
-            <a
-              href={galleryHref}
-              aria-label="Back to gallery"
-              className={cn(
-                buttonVariants({ variant: "text", size: "sm" }),
-                "gap-2 px-0 text-muted-foreground hover:text-foreground",
-              )}
-            >
-              <ArrowLeftIcon className="size-4" aria-hidden={true} />
-              <span>Back</span>
-            </a>
-          </div>
-        )}
-      </AppHeader>
-      <ProgressiveBoundary
-        requires={canPaintRunAppAtom}
-        delay={2000}
-        fallback={
-          <>
-            <Spinner className="mx-auto" />
-            <p className="text-center text-sm text-muted-foreground mt-2">
-              Connecting...
-            </p>
-          </>
-        }
-      >
-        <CellsRenderer appConfig={appConfig} mode="read" />
-      </ProgressiveBoundary>
-    </AppContainer>
+        <KernelStartupErrorModal />
+        <AppHeader
+          connection={connection}
+          className={hideHeader ? "hidden" : "sm:pt-8"}
+        >
+          {galleryHref && (
+            <div className="flex items-center px-6 pt-4 sm:-mt-8">
+              <a
+                href={galleryHref}
+                aria-label="Back to gallery"
+                className={cn(
+                  buttonVariants({ variant: "text", size: "sm" }),
+                  "gap-2 px-0 text-muted-foreground hover:text-foreground",
+                )}
+              >
+                <ArrowLeftIcon className="size-4" aria-hidden={true} />
+                <span>Back</span>
+              </a>
+            </div>
+          )}
+        </AppHeader>
+        <ProgressiveBoundary
+          requires={canPaintRunAppAtom}
+          delay={2000}
+          fallback={
+            <>
+              <Spinner className="mx-auto" />
+              <p className="text-center text-sm text-muted-foreground mt-2">
+                Connecting...
+              </p>
+            </>
+          }
+        >
+          <CellsRenderer appConfig={appConfig} mode="read" />
+        </ProgressiveBoundary>
+      </AppContainer>
+    </DocumentProvider>
   );
 };

package/src/core/runtime/__tests__/adapter.test.ts

@@ -3,10 +3,10 @@
 import { createStore } from "jotai";
 import { describe, expect, it } from "vitest";
 import { islandsInitializedAtom } from "../../islands/state";
-import { kernelStateAtom } from "../../kernel/state";
+import { MockExecutions } from "@/__mocks__/executions";
 import { connectionAtom } from "../../network/connection";
 import { wasmInitStateAtom } from "../../wasm/state";
-import { ConnectionState } from "../../websocket/types";
+import { ConnectionState } from "../../session/types";
 import {
   canRunCellsAtom,
   islandsAdapter,
@@ -122,13 +122,13 @@ describe("islandsAdapter", () => {
 });
 
 describe("canRunCellsAtom", () => {
-  it("is false on a remote adapter until kernel acks", () => {
+  it("is false on a remote adapter until the host reports the runtime running", () => {
     const store = createStore();
     // Default adapter in test env is remote.
     store.set(connectionAtom, { state: ConnectionState.OPEN });
     expect(store.get(canRunCellsAtom)).toBe(false);
 
-    store.set(kernelStateAtom, { isInstantiated: true, error: null });
+    MockExecutions.seed(store, [], MockExecutions.runtime("running"));
     expect(store.get(canRunCellsAtom)).toBe(true);
   });
 

package/src/core/runtime/__tests__/createWsUrl.test.ts

@@ -13,7 +13,9 @@ describe("RuntimeManager.getWsURL", () => {
     });
     const sessionId = "1234" as SessionId;
     const url = runtime.getWsURL(sessionId);
-    expect(url.toString()).toBe("wss://marimo.app/ws?session_id=1234");
+    expect(url.toString()).toBe(
+      "wss://marimo.app/ws?query_params=&session_id=1234",
+    );
     expect(url.searchParams.get(KnownQueryParams.sessionId)).toBe(sessionId);
   });
 
@@ -24,7 +26,9 @@ describe("RuntimeManager.getWsURL", () => {
     });
     const sessionId = "1234" as SessionId;
     const url = runtime.getWsURL(sessionId);
-    expect(url.toString()).toBe("ws://marimo.app/ws?session_id=1234");
+    expect(url.toString()).toBe(
+      "ws://marimo.app/ws?query_params=&session_id=1234",
+    );
     expect(url.searchParams.get(KnownQueryParams.sessionId)).toBe(sessionId);
   });
 
@@ -35,7 +39,9 @@ describe("RuntimeManager.getWsURL", () => {
     });
     const sessionId = "1234" as SessionId;
     const url = runtime.getWsURL(sessionId);
-    expect(url.toString()).toBe("ws://marimo.app/nested/ws?session_id=1234");
+    expect(url.toString()).toBe(
+      "ws://marimo.app/nested/ws?query_params=&session_id=1234",
+    );
     expect(url.searchParams.get(KnownQueryParams.sessionId)).toBe(sessionId);
   });
 
@@ -48,7 +54,7 @@ describe("RuntimeManager.getWsURL", () => {
     const sessionId = "1234" as SessionId;
     const url = runtime.getWsURL(sessionId);
     expect(url.toString()).toBe(
-      "ws://marimo.app/nested/ws?foo=bar&file=test.py&session_id=1234",
+      "ws://marimo.app/nested/ws?foo=bar&file=test.py&query_params=foo%3Dbar%26file%3Dtest.py&session_id=1234",
     );
     expect(url.searchParams.get(KnownQueryParams.sessionId)).toBe(sessionId);
   });
@@ -62,11 +68,75 @@ describe("RuntimeManager.getWsURL", () => {
     const sessionId = "1234" as SessionId;
     const url = runtime.getWsURL(sessionId);
     expect(url.toString()).toBe(
-      "ws://marimo.app/ws?file=test.py&search=test&other=last&session_id=1234",
+      "ws://marimo.app/ws?file=test.py&query_params=file%3Dtest.py%26search%3Dtest%26other%3Dlast&session_id=1234",
     );
     expect(url.searchParams.get("file")).toBe("test.py");
-    expect(url.searchParams.get("search")).toBe("test");
-    expect(url.searchParams.get("other")).toBe("last");
+    expect(url.searchParams.get("query_params")).toBe(
+      "file=test.py&search=test&other=last",
+    );
     expect(url.searchParams.get(KnownQueryParams.sessionId)).toBe(sessionId);
   });
 });
+
+describe.each(["getWsURL", "getSseURL"] as const)(
+  "RuntimeManager.%s",
+  (method) => {
+    it("preserves runtime parameters and repeated page values", () => {
+      window.history.pushState({}, "", "/?tag=page-one&tag=page-two");
+      const runtime = new RuntimeManager(
+        {
+          url: `${window.location.origin}/nested?proxy_token=secret&tag=base&base=one&base=two`,
+          lazy: true,
+        },
+        true,
+      );
+      const url = runtime[method]("session" as SessionId);
+      expect([...url.searchParams]).toEqual([
+        ["proxy_token", "secret"],
+        ["tag", "base"],
+        ["base", "one"],
+        ["base", "two"],
+        [
+          "query_params",
+          "proxy_token=secret&base=one&base=two&tag=page-one&tag=page-two",
+        ],
+        ["session_id", "session"],
+      ]);
+    });
+
+    it("keeps notebook parameters out of the stream options", () => {
+      const notebookParams = new URLSearchParams([
+        ["types", "scatter"],
+        ["cursor", "page-2"],
+        ["run_id", "experiment"],
+        ["query_params", "nested=value&other=1"],
+        ["tag", "one"],
+        ["tag", "two"],
+        ["empty", ""],
+        ["text", "a+b & café"],
+        ["file", "test.py"],
+        ["kiosk", "true"],
+      ]);
+      window.history.pushState(
+        {},
+        "",
+        `/?${notebookParams}&session_id=page-session`,
+      );
+      const runtime = new RuntimeManager(
+        { url: window.location.origin, lazy: true },
+        true,
+      );
+      const url = runtime[method]("actual-session" as SessionId);
+
+      expect(Object.fromEntries(url.searchParams)).toEqual({
+        file: "test.py",
+        kiosk: "true",
+        session_id: "actual-session",
+        query_params: notebookParams.toString(),
+      });
+      expect([
+        ...new URLSearchParams(url.searchParams.get("query_params") ?? ""),
+      ]).toEqual([...notebookParams]);
+    });
+  },
+);