@marimo-team/frontend 0.25.1-dev90 → 0.25.1

package/src/core/islands/components/web-components.tsx

@@ -51,7 +51,7 @@ export class MarimoIslandElement extends HTMLElement {
   public static readonly editorTagName = ISLAND_TAG_NAMES.CODE_EDITOR;
   public static readonly styleNamespace = ISLAND_CSS_CLASSES.NAMESPACE;
 
-  constructor() {
+  public constructor() {
     super();
     this.classList.add(MarimoIslandElement.styleNamespace);
   }
@@ -59,7 +59,7 @@ export class MarimoIslandElement extends HTMLElement {
   /**
    * Gets the app ID from the element's data attribute
    */
-  get appId(): string {
+  public get appId(): string {
     const appId = this.getAttribute(ISLAND_DATA_ATTRIBUTES.APP_ID);
     invariant(appId, "Missing data-app-id attribute");
     return appId;
@@ -68,7 +68,7 @@ export class MarimoIslandElement extends HTMLElement {
   /**
    * Whether this island is reactive (has code sent to Python for execution)
    */
-  get isReactive(): boolean {
+  public get isReactive(): boolean {
     return this.getAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE) === "true";
   }
 
@@ -76,7 +76,7 @@ export class MarimoIslandElement extends HTMLElement {
    * Gets the cell ID by looking up the cell index in the notebook state.
    * Returns undefined for non-reactive islands (they have no corresponding cell).
    */
-  get cellId(): CellId | undefined {
+  public get cellId(): CellId | undefined {
     if (!this.isReactive) {
       return undefined;
     }
@@ -95,7 +95,7 @@ export class MarimoIslandElement extends HTMLElement {
   /**
    * Gets the code for this island cell
    */
-  get code(): string {
+  public get code(): string {
     return extractIslandCodeFromEmbed(this);
   }
 
@@ -115,7 +115,7 @@ export class MarimoIslandElement extends HTMLElement {
    * which can happen inside a React render cycle. Rendering
    * synchronously from there causes "unmount during render" warnings.
    */
-  connectedCallback(): void {
+  public connectedCallback(): void {
     const connectionGeneration = ++this.connectionGeneration;
     this.addEventListener(
       ISLAND_SOURCE_CHANGED_EVENT,
@@ -296,7 +296,7 @@ export class MarimoIslandElement extends HTMLElement {
   /**
    * Cleanup when element is removed from DOM
    */
-  disconnectedCallback(): void {
+  public disconnectedCallback(): void {
     this.removeEventListener(
       ISLAND_SOURCE_CHANGED_EVENT,
       this.handleSourceChanged,

package/src/core/islands/worker/__tests__/controller.test.ts

@@ -5,7 +5,7 @@ import { describe, expect, it, vi } from "vitest";
 import { ReadonlyWasmController } from "../controller";
 
 class TestController extends ReadonlyWasmController {
-  setPyodide(pyodide: PyodideInterface) {
+  public setPyodide(pyodide: PyodideInterface) {
     this.pyodide = pyodide;
   }
 }

package/src/core/islands/worker/controller.ts

@@ -9,7 +9,7 @@ import type { JsonString } from "@/utils/json/base64";
 import { Logger } from "../../../utils/Logger";
 
 export class ReadonlyWasmController extends DefaultWasmController {
-  override async bootstrap(opts: {
+  public override async bootstrap(opts: {
     version: string;
     pyodideVersion: string;
   }): Promise<PyodideInterface> {
@@ -17,7 +17,10 @@ export class ReadonlyWasmController extends DefaultWasmController {
     return pyodide;
   }
 
-  override async mountFilesystem(opts: { code: string; filename: string }) {
+  public override async mountFilesystem(opts: {
+    code: string;
+    filename: string;
+  }) {
     const { code, filename } = opts;
     // Write file
     try {
@@ -34,7 +37,7 @@ export class ReadonlyWasmController extends DefaultWasmController {
     return { code, filename };
   }
 
-  override async startSession(opts: {
+  public override async startSession(opts: {
     code: string;
     filename: string | null;
     onMessage: (message: JsonString<NotificationPayload>) => void;

package/src/core/islands/worker-factory.ts

@@ -39,7 +39,7 @@ export class DefaultWorkerFactory implements WorkerFactory {
   private readonly url: string;
   private readonly name: string;
 
-  constructor(config: DefaultWorkerFactoryConfig = {}) {
+  public constructor(config: DefaultWorkerFactoryConfig = {}) {
     this.url = config.workerUrl || this.getDefaultWorkerUrl();
     this.name = config.workerName || getMarimoVersion();
   }
@@ -47,7 +47,7 @@ export class DefaultWorkerFactory implements WorkerFactory {
   /**
    * Creates a new Pyodide worker
    */
-  create(): Worker {
+  public create(): Worker {
     return createModuleWorker(new URL(this.url, import.meta.url), {
       name: this.name,
     });

package/src/core/kernel/RuntimeState.ts

@@ -17,7 +17,7 @@ export class RuntimeState {
   /**
    * Shared instance of RuntimeState since this must be a singleton.
    */
-  static get INSTANCE(): RuntimeState {
+  public static get INSTANCE(): RuntimeState {
     const KEY = "_marimo_private_RuntimeState";
     if (!window[KEY]) {
       window[KEY] = new RuntimeState(UI_ELEMENT_REGISTRY);
@@ -31,7 +31,7 @@ export class RuntimeState {
   private _sendComponentValues: RunRequests["sendComponentValues"] | undefined;
   private uiElementRegistry: UIElementRegistry;
 
-  constructor(uiElementRegistry: UIElementRegistry) {
+  public constructor(uiElementRegistry: UIElementRegistry) {
     this.uiElementRegistry = uiElementRegistry;
   }
 
@@ -45,7 +45,7 @@ export class RuntimeState {
   /**
    * Start listening for events from UIElements
    */
-  start(sendComponentValues: RunRequests["sendComponentValues"]) {
+  public start(sendComponentValues: RunRequests["sendComponentValues"]) {
     if (this.hasStarted) {
       Logger.warn("RuntimeState already started");
       return;
@@ -61,7 +61,7 @@ export class RuntimeState {
   /**
    * Stop listening for events from UIElements
    */
-  stop() {
+  public stop() {
     if (!this.hasStarted) {
       Logger.warn("RuntimeState already stopped");
       return;

package/src/core/kernel/__tests__/session.test.ts

@@ -1,10 +1,119 @@
 /* Copyright 2026 Marimo. All rights reserved. */
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { AppMode } from "@/core/mode";
 import { generateSessionId, isSessionId } from "../session";
 
+const URL_SESSION_ID = "s_abc123";
+
+/**
+ * Load a fresh copy of the session module against the given URL and mode.
+ * The module caches its session id, so each case needs its own instance.
+ */
+async function loadSession(opts: { mode: AppMode | undefined; url: string }) {
+  vi.resetModules();
+  window.history.replaceState({}, "", opts.url);
+  const { store } = await import("@/core/state/jotai");
+  const { initialModeAtom } = await import("@/core/mode");
+  store.set(initialModeAtom, opts.mode);
+  return await import("../session");
+}
+
+function currentSearchParams(): URLSearchParams {
+  return new URL(window.location.href).searchParams;
+}
+
 describe("Session", () => {
+  afterEach(() => {
+    window.history.replaceState({}, "", "/");
+  });
+
   it("should create a session", () => {
     const id = generateSessionId();
     expect(isSessionId(id)).toBe(true);
   });
+
+  it("resumes the session named in the URL in edit mode", async () => {
+    const { getSessionId } = await loadSession({
+      mode: "edit",
+      url: `/?session_id=${URL_SESSION_ID}`,
+    });
+    expect(getSessionId()).toBe(URL_SESSION_ID);
+    expect(currentSearchParams().has("session_id")).toBe(false);
+  });
+
+  it("keeps the URL session id in kiosk mode so a refresh resumes it", async () => {
+    const { getSessionId } = await loadSession({
+      mode: "edit",
+      url: `/?kiosk=true&session_id=${URL_SESSION_ID}`,
+    });
+    expect(getSessionId()).toBe(URL_SESSION_ID);
+    expect(currentSearchParams().get("session_id")).toBe(URL_SESSION_ID);
+    expect(currentSearchParams().get("kiosk")).toBe("true");
+  });
+
+  it("keeps the kiosk flag in edit mode when the URL names no session", async () => {
+    const { getSessionId } = await loadSession({
+      mode: "edit",
+      url: "/?kiosk=true",
+    });
+    expect(isSessionId(getSessionId())).toBe(true);
+    expect(currentSearchParams().get("kiosk")).toBe("true");
+  });
+
+  it("starts a new session when the URL session id is malformed", async () => {
+    const { getSessionId } = await loadSession({
+      mode: "edit",
+      url: "/?session_id=not-a-session",
+    });
+    const id = getSessionId();
+    expect(isSessionId(id)).toBe(true);
+    expect(id).not.toBe("not-a-session");
+  });
+
+  it("ignores the URL session id in read mode", async () => {
+    const { getSessionId } = await loadSession({
+      mode: "read",
+      url: `/?session_id=${URL_SESSION_ID}`,
+    });
+    const id = getSessionId();
+    expect(isSessionId(id)).toBe(true);
+    expect(id).not.toBe(URL_SESSION_ID);
+    // The param is still scrubbed so a refresh cannot reintroduce it.
+    expect(currentSearchParams().has("session_id")).toBe(false);
+  });
+
+  it("drops both the session id and the kiosk flag in read mode", async () => {
+    const { getSessionId } = await loadSession({
+      mode: "read",
+      url: `/?kiosk=true&session_id=${URL_SESSION_ID}`,
+    });
+    expect(getSessionId()).not.toBe(URL_SESSION_ID);
+    expect(currentSearchParams().has("session_id")).toBe(false);
+    // The kiosk flag is forwarded to the websocket URL, and the server
+    // refuses kiosk connections to an app, so it must not survive here.
+    expect(currentSearchParams().has("kiosk")).toBe(false);
+  });
+
+  it("drops a lone kiosk flag in read mode", async () => {
+    const { getSessionId } = await loadSession({
+      mode: "read",
+      url: "/?kiosk=true",
+    });
+    expect(isSessionId(getSessionId())).toBe(true);
+    expect(currentSearchParams().has("kiosk")).toBe(false);
+  });
+
+  it("ignores the URL session id when the mode is not yet known", async () => {
+    const { getSessionId } = await loadSession({
+      mode: undefined,
+      url: `/?session_id=${URL_SESSION_ID}`,
+    });
+    expect(getSessionId()).not.toBe(URL_SESSION_ID);
+    expect(currentSearchParams().has("session_id")).toBe(false);
+  });
+
+  it("returns the same id on every call", async () => {
+    const { getSessionId } = await loadSession({ mode: "read", url: "/" });
+    expect(getSessionId()).toBe(getSessionId());
+  });
 });

package/src/core/kernel/session.ts

@@ -4,6 +4,8 @@ import { Logger } from "@/utils/Logger";
 import type { TypedString } from "@/utils/typed";
 import { updateQueryParams } from "@/utils/urls";
 import { KnownQueryParams } from "../constants";
+import { initialModeAtom } from "../mode";
+import { store } from "../state/jotai";
 
 export type SessionId = TypedString<"SessionId">;
 
@@ -20,31 +22,60 @@ export function isSessionId(value: string | null): value is SessionId {
   return /^s_[\da-z]{6}$/.test(value);
 }
 
-const sessionId = (() => {
+let sessionId: SessionId | null = null;
+
+function resolveSessionId(): SessionId {
+  // Only the editor lets the URL steer the connection: kiosk mode and
+  // external editors reattach to a running session through `session_id`.
+  // An app served with `marimo run` never does. There, the session id is the
+  // only thing that routes a browser to its kernel, so a link that picked it
+  // would let the link's author attach to the reader's session afterwards,
+  // and a stray `kiosk` flag would make the server refuse the connection.
+  const urlMaySteerConnection = store.get(initialModeAtom) === "edit";
+
   const url = new URL(window.location.href);
   const id = url.searchParams.get(
     KnownQueryParams.sessionId,
   ) as SessionId | null;
-  if (isSessionId(id)) {
-    // Remove the session_id from the URL
-    updateQueryParams((params) => {
-      // Keep the session_id if we are in kiosk mode
-      // this is so we can resume the same session if the user refreshes the page
-      if (params.has(KnownQueryParams.kiosk)) {
-        return;
-      }
+  const urlSessionId = isSessionId(id) ? id : null;
+
+  updateQueryParams((params) => {
+    if (!urlMaySteerConnection) {
       params.delete(KnownQueryParams.sessionId);
+      params.delete(KnownQueryParams.kiosk);
+      return;
+    }
+    // Keep the session_id in kiosk mode so that a refresh resumes the same
+    // session.
+    if (params.has(KnownQueryParams.kiosk)) {
+      return;
+    }
+    params.delete(KnownQueryParams.sessionId);
+  });
+
+  if (urlSessionId === null) {
+    Logger.debug("Starting a new session", { sessionId: id });
+    return generateSessionId();
+  }
+  if (!urlMaySteerConnection) {
+    Logger.debug("Ignoring session_id from URL outside the editor", {
+      sessionId: urlSessionId,
     });
-    Logger.debug("Connecting to existing session", { sessionId: id });
-    return id;
+    return generateSessionId();
   }
-  Logger.debug("Starting a new session", { sessionId: id });
-  return generateSessionId();
-})();
+  Logger.debug("Connecting to existing session", { sessionId: urlSessionId });
+  return urlSessionId;
+}
 
 /**
- * Resume an existing session or start a new one
+ * Resume an existing session or start a new one.
+ *
+ * Resolved on first use rather than at import time, because the URL is only
+ * trusted once the app mode is known.
  */
 export function getSessionId(): SessionId {
+  if (sessionId === null) {
+    sessionId = resolveSessionId();
+  }
   return sessionId;
 }

package/src/core/lsp/__tests__/transport.test.ts

@@ -10,28 +10,28 @@ vi.mock("@/utils/Logger", () => ({
 }));
 
 class FakeWebSocket {
-  static readonly CONNECTING = 0;
-  static readonly OPEN = 1;
-  static readonly CLOSING = 2;
-  static readonly CLOSED = 3;
-  static readonly instances: FakeWebSocket[] = [];
-
-  readonly sent: string[] = [];
-  readonly url: string;
-  readonly protocols: string | string[] | undefined;
-  readyState = FakeWebSocket.CONNECTING;
+  public static readonly CONNECTING = 0;
+  public static readonly OPEN = 1;
+  public static readonly CLOSING = 2;
+  public static readonly CLOSED = 3;
+  public static readonly instances: FakeWebSocket[] = [];
+
+  public readonly sent: string[] = [];
+  public readonly url: string;
+  public readonly protocols: string | string[] | undefined;
+  public readyState = FakeWebSocket.CONNECTING;
   private readonly listeners = new Map<
     string,
     Set<(event: { data?: unknown }) => void>
   >();
 
-  constructor(url: string, protocols?: string | string[]) {
+  public constructor(url: string, protocols?: string | string[]) {
     this.url = url;
     this.protocols = protocols;
     FakeWebSocket.instances.push(this);
   }
 
-  addEventListener(
+  public addEventListener(
     type: string,
     listener: (event: { data?: unknown }) => void,
   ) {
@@ -40,34 +40,34 @@ class FakeWebSocket {
     this.listeners.set(type, listeners);
   }
 
-  send(frame: string) {
+  public send(frame: string) {
     this.sent.push(frame);
   }
 
-  close() {
+  public close() {
     this.readyState = FakeWebSocket.CLOSED;
     this.emit("close", {});
   }
 
-  open() {
+  public open() {
     this.readyState = FakeWebSocket.OPEN;
     this.emit("open", {});
   }
 
-  fail() {
+  public fail() {
     this.emit("error", {});
   }
 
-  disconnect() {
+  public disconnect() {
     this.readyState = FakeWebSocket.CLOSED;
     this.emit("close", {});
   }
 
-  receive(message: JSONRPCMessage) {
+  public receive(message: JSONRPCMessage) {
     this.emit("message", { data: JSON.stringify(message) });
   }
 
-  messages(): JSONRPCMessage[] {
+  public messages(): JSONRPCMessage[] {
     return this.sent.map((frame) => {
       const message: unknown = JSON.parse(frame);
       if (!isJSONRPCMessage(message)) {

package/src/core/lsp/transport.ts

@@ -100,7 +100,7 @@ export class ReconnectingWebSocketTransport implements Transport {
 
   public onReconnect: (() => Promise<void>) | undefined;
 
-  constructor(options: ReconnectingWebSocketTransportOptions) {
+  public constructor(options: ReconnectingWebSocketTransportOptions) {
     this.options = {
       ...options,
       retries: options.retries ?? 1,
@@ -109,7 +109,7 @@ export class ReconnectingWebSocketTransport implements Transport {
     this.onReconnect = options.onReconnect;
   }
 
-  async connect(): Promise<void> {
+  public async connect(): Promise<void> {
     if (this.isClosed) {
       throw new Error("Transport is closed");
     }
@@ -136,7 +136,7 @@ export class ReconnectingWebSocketTransport implements Transport {
     return this.isClosed || generation !== this.connectionGeneration;
   }
 
-  send(message: JSONRPCMessage): void {
+  public send(message: JSONRPCMessage): void {
     if (this.isClosed) {
       return;
     }
@@ -162,14 +162,14 @@ export class ReconnectingWebSocketTransport implements Transport {
     this.reconnect();
   }
 
-  onMessage(handler: (message: JSONRPCMessage) => void): () => void {
+  public onMessage(handler: (message: JSONRPCMessage) => void): () => void {
     this.messageHandlers.add(handler);
     return () => {
       this.messageHandlers.delete(handler);
     };
   }
 
-  close(): void {
+  public close(): void {
     if (this.isClosed) {
       return;
     }

package/src/core/network/CachingRequestRegistry.ts

@@ -22,7 +22,7 @@ export class CachingRequestRegistry<REQ, RES> {
   private toKey: ToKey<REQ>;
   private cache: LRUCache<string, Promise<RES>>;
 
-  static jsonStringifySortKeys<T>(): ToKey<T> {
+  public static jsonStringifySortKeys<T>(): ToKey<T> {
     return (o: T) => {
       if (typeof o !== "object" || o === null) {
         return String(o);
@@ -31,7 +31,7 @@ export class CachingRequestRegistry<REQ, RES> {
     };
   }
 
-  constructor(
+  public constructor(
     delegate: DeferredRequestRegistry<REQ, RES>,
     options: CachingOptions<REQ> = {},
   ) {

package/src/core/network/DeferredRequestRegistry.ts

@@ -27,7 +27,7 @@ export class DeferredRequestRegistry<REQ, RES> {
     resolveExistingRequests?: () => RES;
   };
 
-  constructor(
+  public constructor(
     operation: string,
     makeRequest: (id: RequestId, req: REQ) => Promise<void>,
     opts: {
@@ -42,7 +42,7 @@ export class DeferredRequestRegistry<REQ, RES> {
     this.opts = opts;
   }
 
-  async request(opts: REQ): Promise<RES> {
+  public async request(opts: REQ): Promise<RES> {
     if (this.opts.resolveExistingRequests) {
       const result = this.opts.resolveExistingRequests();
       for (const deferred of this.requests.values()) {
@@ -63,7 +63,7 @@ export class DeferredRequestRegistry<REQ, RES> {
     return deferred.promise;
   }
 
-  resolve(requestId: RequestId, response: RES) {
+  public resolve(requestId: RequestId, response: RES) {
     const entry = this.requests.get(requestId);
     if (entry === undefined) {
       return;
@@ -73,7 +73,7 @@ export class DeferredRequestRegistry<REQ, RES> {
     this.requests.delete(requestId);
   }
 
-  reject(requestId: RequestId, error: Error) {
+  public reject(requestId: RequestId, error: Error) {
     const entry = this.requests.get(requestId);
     if (entry === undefined) {
       return;

package/src/core/network/__tests__/export-asset-url.test.ts

@@ -0,0 +1,45 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { afterEach, describe, expect, it } from "vitest";
+import { withDevAssetUrl } from "../export-asset-url";
+import type { ExportAsHTMLRequest } from "../types";
+
+const REQUEST: ExportAsHTMLRequest = {
+  download: false,
+  includeCode: true,
+  files: [],
+};
+
+describe("withDevAssetUrl", () => {
+  const originalEnv = process.env.NODE_ENV;
+
+  afterEach(() => {
+    process.env.NODE_ENV = originalEnv;
+  });
+
+  it.each(["development", "test"])(
+    "defaults assetUrl to the dev server in %s",
+    (env) => {
+      process.env.NODE_ENV = env;
+      expect(withDevAssetUrl(REQUEST).assetUrl).toBe(window.location.origin);
+    },
+  );
+
+  it("leaves a caller-provided assetUrl alone in dev", () => {
+    process.env.NODE_ENV = "development";
+    const cdn = "https://cdn.example.com/dist";
+    expect(withDevAssetUrl({ ...REQUEST, assetUrl: cdn }).assetUrl).toBe(cdn);
+  });
+
+  it("does nothing in production", () => {
+    process.env.NODE_ENV = "production";
+    expect(withDevAssetUrl(REQUEST)).toBe(REQUEST);
+  });
+
+  it("does not mutate the caller's request", () => {
+    process.env.NODE_ENV = "development";
+    const request = { ...REQUEST };
+    withDevAssetUrl(request);
+    expect(request.assetUrl).toBeUndefined();
+  });
+});

package/src/core/network/export-asset-url.ts

@@ -0,0 +1,19 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type { ExportAsHTMLRequest } from "./types";
+
+/**
+ * In dev/test the CDN has no assets for the local build, so exports default
+ * to the dev server. Callers publishing to a remote origin pass their own
+ * assetUrl, which is left untouched.
+ */
+export function withDevAssetUrl(
+  request: ExportAsHTMLRequest,
+): ExportAsHTMLRequest {
+  const isDevOrTest =
+    process.env.NODE_ENV === "development" || process.env.NODE_ENV === "test";
+  if (request.assetUrl == null && isDevOrTest) {
+    return { ...request, assetUrl: window.location.origin };
+  }
+  return request;
+}

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

@@ -11,6 +11,7 @@ import {
   waitForConnectionOpen,
   waitForConnectionOpenIfNotebook,
 } from "./connection";
+import { withDevAssetUrl } from "./export-asset-url";
 import type { EditRequests, RunRequests } from "./types";
 
 /**
@@ -430,15 +431,9 @@ export function createNetworkRequests(): EditRequests & RunRequests {
         .then(handleResponse);
     },
     exportAsHTML: async (request) => {
-      if (
-        process.env.NODE_ENV === "development" ||
-        process.env.NODE_ENV === "test"
-      ) {
-        request.assetUrl = window.location.origin;
-      }
       return getClient()
         .POST("/api/export/html", {
-          body: request,
+          body: withDevAssetUrl(request),
           parseAs: "text",
           params: getParams(),
         })