@marimo-team/islands 0.25.3-dev192 → 0.25.3-dev193

package/src/core/saving/state.ts

@@ -1,52 +1,51 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
+/** Whether the notebook has changes the host has not written to its store. */
+
 import { dequal as isEqual } from "dequal";
 import { atom } from "jotai";
-import { arrayShallowEquals } from "@/utils/arrays";
-import { type NotebookState, notebookAtom } from "../cells/cells";
 import { type LayoutState, layoutStateAtom } from "../layout/state";
-import type { CellConfig } from "../network/types";
-
-export interface LastSavedNotebook {
-  codes: string[];
-  configs: CellConfig[];
-  names: string[];
-  layout: LayoutState;
-}
+import {
+  activeDocumentModelAtom,
+  confirmedDocumentAtom,
+} from "../session/active-notebook";
 
-export const lastSavedNotebookAtom = atom<LastSavedNotebook | undefined>(
-  undefined,
+/** The document version, which counts confirmed changes. Null without a document. */
+export const documentVersionAtom = atom(
+  (get) => get(confirmedDocumentAtom)?.revision.version ?? null,
 );
 
-export const needsSaveAtom = atom((get) => {
-  const lastSavedNotebook = get(lastSavedNotebookAtom);
-  const state = get(notebookAtom);
-  const layout = get(layoutStateAtom);
-  return notebookNeedsSave({ state, layout, lastSavedNotebook });
-});
+/**
+ * The layout as the file last had it. The host document does not carry
+ * the layout file, so this client compares it itself until it does.
+ */
+export const savedLayoutAtom = atom<LayoutState | undefined>(undefined);
 
-function notebookNeedsSave({
-  state,
-  layout,
-  lastSavedNotebook,
-}: {
-  state: NotebookState;
-  layout: LayoutState;
-  lastSavedNotebook: LastSavedNotebook | undefined;
-}) {
-  if (!lastSavedNotebook) {
+/**
+ * Whether saving would change the file: the host's document differs from
+ * what it last wrote, this client has edits the host has not confirmed,
+ * or the layout changed. A document never written reports as unsaved.
+ */
+export const needsSaveAtom = atom((get) => {
+  const document = get(confirmedDocumentAtom);
+  if (document === null) {
     return false;
   }
-  const { cellIds, cellData } = state;
-  const data = cellIds.inOrderIds.map((cellId) => cellData[cellId]);
-  const codes = data.map((d) => d.code);
-  const configs = data.map((d) => d.config);
-  const names = data.map((d) => d.name);
+  if (document.revision.etag !== document.revision.saved_etag) {
+    return true;
+  }
+  const model = get(activeDocumentModelAtom);
+  if (model !== null) {
+    const { status } = get(model.syncStatusAtom);
+    if (status !== "idle" && status !== "unavailable") {
+      return true;
+    }
+  }
+  const saved = get(savedLayoutAtom);
+  const layout = get(layoutStateAtom);
   return (
-    !arrayShallowEquals(codes, lastSavedNotebook.codes) ||
-    !arrayShallowEquals(names, lastSavedNotebook.names) ||
-    !isEqual(configs, lastSavedNotebook.configs) ||
-    !isEqual(layout.selectedLayout, lastSavedNotebook.layout.selectedLayout) ||
-    !isEqual(layout.layoutData, lastSavedNotebook.layout.layoutData)
+    saved !== undefined &&
+    (layout.selectedLayout !== saved.selectedLayout ||
+      !isEqual(layout.layoutData, saved.layoutData))
   );
-}
+});

package/src/core/saving/useAutoSave.ts

@@ -1,40 +1,23 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 import { useEffect, useRef } from "react";
 import type { UserConfig } from "../config/config-schema";
-import type { CellConfig } from "../network/types";
 import { type ConnectionStatus, ConnectionState } from "../session/types";
 
+/** Save after a delay while the notebook needs it, restarting on every confirmed change. */
 export function useAutoSave(opts: {
-  codes: string[];
-  cellConfigs: CellConfig[];
-  cellNames: string[];
+  /** The document version, which counts confirmed changes. */
+  version: number | null;
   config: UserConfig["save"];
   connStatus: ConnectionStatus;
   needsSave: boolean;
-  kioskMode: boolean;
+  canEdit: boolean;
   onSave: () => void;
 }) {
-  const {
-    codes,
-    cellConfigs,
-    config,
-    connStatus,
-    cellNames,
-    needsSave,
-    kioskMode,
-    onSave,
-  } = opts;
+  const { version, config, connStatus, needsSave, canEdit, onSave } = opts;
   const autosaveTimeoutId = useRef<NodeJS.Timeout | null>(null);
 
-  const codesString = codes.join(":");
-  const cellConfigsString = cellConfigs
-    .map((config) => JSON.stringify(config))
-    .join(":");
-  const cellNamesString = cellNames.join(":");
-
   useEffect(() => {
-    // If kiosk mode is enabled, do not autosave
-    if (kioskMode) {
+    if (!canEdit) {
       return;
     }
 
@@ -53,16 +36,6 @@ export function useAutoSave(opts: {
         clearTimeout(autosaveTimeoutId.current);
       }
     };
-    // codes, cellConfigs, cellNames needed in deps array to prevent race condition
-    // with needsSave when user changes state rapidly
-  }, [
-    codesString,
-    cellConfigsString,
-    cellNamesString,
-    config,
-    connStatus.state,
-    onSave,
-    kioskMode,
-    needsSave,
-  ]);
+    // `version` restarts the delay on every confirmed change.
+  }, [version, config, connStatus.state, onSave, canEdit, needsSave]);
 }

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

@@ -27,6 +27,7 @@ afterEach(() => {
 
 const options = {
   static: false,
+  snapshot: null,
   transportType: "websocket" as const,
   url: () => "ws://localhost/ws",
   headers: () => ({}),

package/src/core/session/__tests__/useNotebookReplica.hook.test.tsx

@@ -48,6 +48,7 @@ function setup(strict = false) {
   const store = createStore();
   const options = {
     static: false,
+    snapshot: null,
     transportType: "websocket" as const,
     url: () => "ws://localhost/ws",
     headers: () => ({}),

package/src/core/session/active-notebook.ts

@@ -9,3 +9,14 @@ export const activeNotebookReplicaAtom = atom<NotebookReplica | null>(null);
 
 /** The document model owned by the mounted notebook session. */
 export const activeDocumentModelAtom = atom<DocumentModel | null>(null);
+
+/**
+ * The document the host last confirmed, or null while no notebook is
+ * connected. Facts the host owns read this one, such as permission, the
+ * app config, saved state and whether source is available. What the user
+ * is editing reads the model's document, which adds this browser's drafts.
+ */
+export const confirmedDocumentAtom = atom((get) => {
+  const replica = get(activeNotebookReplicaAtom);
+  return replica === null ? null : get(replica.documentAtom);
+});

package/src/core/session/backend.ts

@@ -8,11 +8,18 @@ import type { NotebookBackend } from "../notebook/replica";
 import { PyodideBridge } from "../wasm/bridge";
 import { isWasm } from "../wasm/utils";
 import { sessionSse, websocket, withHeaders } from "../transports/server";
-import { idle } from "../transports/static";
+import {
+  createStaticNotebookBackend,
+  emptySnapshot,
+  type StaticNotebookSnapshot,
+  startWithSnapshot,
+} from "../transports/static";
 
 /** How the editor follows its notebook. */
 export interface EditorBackendOptions {
   static: boolean;
+  /** The notebook the page was served with, shown until the host answers. */
+  snapshot: StaticNotebookSnapshot | null;
   transportType: "websocket" | "sse";
   /** The session route, read before each connection. */
   url: () => string;
@@ -86,30 +93,21 @@ function wasm(): NotebookBackend {
   };
 }
 
-/** Commands for a notebook the editor cannot change through its backend. */
-function uneditable(): ReturnType<NotebookBackend["notebook"]> {
-  const unsupported: NotebookClient["save"] = async () => ({
-    ok: false,
-    status: 501,
-    problem: {
-      type: "tag:marimo.io,2026:host/unsupported-operation",
-      title: "Document mutations are unavailable on this connection",
-      status: 501,
-    },
-  });
-  return { edit: () => unsupported(), save: unsupported };
-}
-
 /** Choose the backend for the editor's notebook. */
 export function createEditorBackend(
   options: EditorBackendOptions,
 ): NotebookBackend {
   if (options.static) {
-    return { transport: idle, notebook: uneditable };
-  }
-  if (isWasm()) {
-    return wasm();
+    return createStaticNotebookBackend(
+      options.snapshot ?? emptySnapshot("static"),
+    );
   }
+  const live = isWasm() ? wasm() : server(options);
+  return options.snapshot ? startWithSnapshot(options.snapshot, live) : live;
+}
+
+/** Follow the notebook on the server, over SSE or a WebSocket. */
+function server(options: EditorBackendOptions): NotebookBackend {
   const url = afterStartup(options);
   return {
     transport:

package/src/core/session/embedded.ts

@@ -0,0 +1,7 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { atom } from "jotai";
+import type { StaticNotebookSnapshot } from "../transports/static";
+
+/** The notebook the page was served with, read at mount. Null when none was. */
+export const embeddedSnapshotAtom = atom<StaticNotebookSnapshot | null>(null);

package/src/core/session/useNotebookReplica.ts

@@ -22,7 +22,7 @@ type Options = EditorBackendOptions & {
 
 export function useNotebookReplica(options: Options): NotebookReplica {
   const store = useStore();
-  const { static: isStatic, transportType } = options;
+  const { static: isStatic, snapshot, transportType } = options;
   const replica = useMemo(() => createNotebookReplica(store), [store]);
   const url = useEvent(options.url);
   const headers = useEvent(options.headers);
@@ -35,6 +35,7 @@ export function useNotebookReplica(options: Options): NotebookReplica {
     () =>
       createEditorBackend({
         static: isStatic,
+        snapshot,
         transportType,
         url,
         headers,
@@ -44,6 +45,7 @@ export function useNotebookReplica(options: Options): NotebookReplica {
       }),
     [
       isStatic,
+      snapshot,
       transportType,
       url,
       headers,

package/src/core/session/useNotebookSession.tsx

@@ -35,7 +35,7 @@ import {
 } from "../codemirror/cells/debugger-state";
 import { notebookCells } from "../cells/utils";
 import { capabilitiesAtom } from "../config/capabilities";
-import { connectionTransportTypeAtom, useSetAppConfig } from "../config/config";
+import { connectionTransportTypeAtom } from "../config/config";
 import { useDataSourceActions } from "../datasets/data-source-connections";
 import { invalidateDataSourceDiscovery } from "../datasets/data-source-discovery";
 import type { ConnectionName } from "../datasets/engines";
@@ -62,9 +62,10 @@ import {
   stableSessionIdAtom,
 } from "../kernel/session";
 import { initialRunCompletedAtom, kernelStateAtom } from "../kernel/state";
-import { type LayoutState, useLayoutActions } from "../layout/state";
+import { useLayoutActions } from "../layout/state";
 import { kioskModeAtom } from "../mode";
 import { connectionAtom, startupProgressAtom } from "../network/connection";
+import { savedLayoutAtom } from "../saving/state";
 import type { RequestId } from "../network/DeferredRequestRegistry";
 import { useRuntimeManager } from "../runtime/config";
 import { SECRETS_REGISTRY } from "../secrets/request-registry";
@@ -77,16 +78,15 @@ import { useStorageActions } from "../storage/state";
 import { useVariablesActions } from "../variables/state";
 import type { VariableName } from "../variables/types";
 import { activeDocumentModelAtom } from "./active-notebook";
+import { embeddedSnapshotAtom } from "./embedded";
 import { WebSocketClosedReason, ConnectionState } from "./types";
 
 /** Coordinate session startup and apply notifications to the editor. */
 export function useNotebookSession(opts: {
   sessionId: SessionId;
   autoInstantiate: boolean;
-  /** Called with the layout the kernel reported, after its cells are ready. */
-  onKernelReady?: (layout: LayoutState) => void;
 }) {
-  const { autoInstantiate, sessionId, onKernelReady } = opts;
+  const { autoInstantiate, sessionId } = opts;
   const { showBoundary } = useErrorBoundary();
   const store = useStore();
 
@@ -99,7 +99,6 @@ export function useNotebookSession(opts: {
   const { addCellNotification } = useRunsActions();
   const setKernelState = useSetAtom(kernelStateAtom);
   const setInitialRunCompleted = useSetAtom(initialRunCompletedAtom);
-  const setAppConfig = useSetAppConfig();
   const { setVariables, setMetadata } = useVariablesActions();
   const { addColumnPreview } = useDatasetsActions();
   const { addDatasets, filterDatasetsFromVariables } = useDatasetsActions();
@@ -156,12 +155,11 @@ export function useNotebookSession(opts: {
           setLastRun,
           resetCellRuntimes,
           setLayoutData,
-          setAppConfig,
           setCapabilities,
           setKernelState,
           onError: showBoundary,
         });
-        onKernelReady?.(layout);
+        store.set(savedLayoutAtom, layout);
         if (!msg.data.resumed) {
           // A freshly started kernel may expose a different environment
           // (e.g. new env vars); re-run discovery instead of reusing stale
@@ -399,6 +397,7 @@ export function useNotebookSession(opts: {
   };
   const replica = useNotebookReplica({
     static: isStaticNotebook(),
+    snapshot: useAtomValue(embeddedSnapshotAtom),
     transportType,
     url: () =>
       transportType === "sse"

package/src/core/transports/__tests__/static.test.ts

@@ -3,10 +3,13 @@
 import { createNotebookReducer, NotebookEvents } from "@marimo-team/client";
 import * as Protocol from "@marimo-team/client/protocol";
 import { afterEach, assert, describe, expect, it, vi } from "vitest";
+import type { NotebookBackend } from "../../notebook/replica";
 import { document as documentResource } from "../../notebook/replica/resources/document";
 import {
   createStaticNotebookBackend,
+  emptySnapshot,
   type StaticNotebookSnapshot,
+  startWithSnapshot,
 } from "../static";
 import { fixtureEvents } from "../../notebook/replica/__tests__/fixtures";
 
@@ -34,24 +37,48 @@ afterEach(async () => {
   vi.useRealTimers();
 });
 
-async function read(
-  backend: ReturnType<typeof createStaticNotebookBackend>,
-  cursor?: string,
-) {
-  const stream = new NotebookEvents(backend.transport, { cursor });
-  streams.push(stream);
+/** Collect a stream's events up to and including its next `ready`. */
+function untilReady(stream: NotebookEvents): Promise<Protocol.EventOutput[]> {
   const events: Protocol.EventOutput[] = [];
-  await new Promise<void>((resolve, reject) => {
+  return new Promise((resolve, reject) => {
     stream.subscribe((event) => {
       events.push(Protocol.Event.parse(event));
       if (event.event === "ready") {
-        resolve();
+        resolve(events);
       }
     }, reject);
   });
+}
+
+/** Open a backend's stream and read until it is ready. */
+async function read(
+  backend: ReturnType<typeof createStaticNotebookBackend>,
+  cursor?: string,
+) {
+  const stream = new NotebookEvents(backend.transport, { cursor });
+  streams.push(stream);
+  const events = await untilReady(stream);
   return { stream, events };
 }
 
+/** A live backend whose stream sends nothing until `release` is called. */
+function silentUntilReleased(backend: NotebookBackend) {
+  let release = () => {};
+  const released = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const attempts: Array<string | null> = [];
+  const silent: NotebookBackend = {
+    ...backend,
+    transport: async (attempt, handlers) => {
+      attempts.push(attempt.cursor);
+      await released;
+      return backend.transport(attempt, handlers);
+    },
+  };
+  return { backend: silent, release: () => release(), attempts };
+}
+
 describe("static notebook backend", () => {
   it("supplies a complete document through the normal event reader and reducer", async () => {
     const source = snapshot();
@@ -173,3 +200,107 @@ describe("static notebook backend", () => {
     expect(message).toHaveBeenCalledOnce();
   });
 });
+
+describe("starting from an embedded snapshot", () => {
+  it("shows the snapshot until the host answers, then resets into its stream", async () => {
+    const embedded = snapshot();
+    const live = silentUntilReleased(
+      createStaticNotebookBackend(emptySnapshot("live")),
+    );
+    const reducer = createNotebookReducer({ document: documentResource });
+
+    // The snapshot is published on its own, with the host still silent.
+    const { stream, events } = await read(
+      startWithSnapshot(embedded, live.backend),
+    );
+    expect(events.map((event) => event.event)).toEqual([
+      "notebook",
+      "cell",
+      "cell",
+      "cell",
+      "document",
+      "ready",
+    ]);
+    const shown = events.reduce(reducer.reduce, reducer.initial);
+    expect(shown.notebook?.id).toBe(embedded.notebook.id);
+    expect(shown.resources.document.current?.cells.size).toBe(3);
+    expect(live.attempts).toEqual([null]);
+
+    // The host's first frame discards it, and the host's snapshot follows.
+    const host = untilReady(stream);
+    live.release();
+    const rest = await host;
+    expect(rest.map((event) => event.event)).toEqual([
+      "reset",
+      "notebook",
+      "document",
+      "ready",
+    ]);
+    const state = rest.reduce(reducer.reduce, shown);
+    expect(state.notebook?.id).toBe("live");
+    expect(state.resources.document.current?.cells.size).toBe(0);
+    expect(stream.status).toBe("connected");
+  });
+
+  it("does not open the host when cancelled while showing the snapshot", async () => {
+    const attempts: Array<string | null> = [];
+    const live: NotebookBackend = {
+      ...createStaticNotebookBackend(emptySnapshot("live")),
+      transport: async (attempt) => {
+        attempts.push(attempt.cursor);
+      },
+    };
+    const controller = new AbortController();
+    const message = vi.fn(() => controller.abort());
+
+    await startWithSnapshot(snapshot(), live).transport(
+      { cursor: null, signal: controller.signal },
+      { open: vi.fn(), message },
+    );
+
+    expect(message).toHaveBeenCalledOnce();
+    expect(attempts).toEqual([]);
+  });
+
+  it("starts the host connection fresh when resuming from the snapshot's cursor", async () => {
+    const embedded = snapshot();
+    const live = silentUntilReleased(
+      createStaticNotebookBackend(emptySnapshot("live")),
+    );
+    live.release();
+    const { events } = await read(
+      startWithSnapshot(embedded, live.backend),
+      `${embedded.notebook.id}:snapshot`,
+    );
+    expect(live.attempts).toEqual([null]);
+    expect(events.map((event) => event.event)).toEqual([
+      "reset",
+      "notebook",
+      "document",
+      "ready",
+    ]);
+  });
+
+  it("skips the snapshot when a connection resumes", async () => {
+    const backend = startWithSnapshot(
+      snapshot(),
+      createStaticNotebookBackend(emptySnapshot("live")),
+    );
+    const { events } = await read(backend, "static");
+    expect(events.map((event) => event.event)).toEqual([
+      "reset",
+      "notebook",
+      "document",
+      "ready",
+    ]);
+  });
+
+  it("keeps the live backend's commands", async () => {
+    const backend = startWithSnapshot(
+      snapshot(),
+      createStaticNotebookBackend(emptySnapshot("live")),
+    );
+    const result = await backend.notebook("live").save();
+    expect(result).toMatchObject({ ok: false, status: 501 });
+  });
+});

package/src/core/transports/static.ts

@@ -2,7 +2,7 @@
 
 /** A backend that serves a document snapshot without a host. */
 
-import type { NotebookClient, NotebookTransport } from "@marimo-team/client";
+import type { NotebookClient } from "@marimo-team/client";
 import type * as Protocol from "@marimo-team/client/protocol";
 import type { NotebookBackend } from "../notebook/replica";
 
@@ -13,14 +13,9 @@ export interface StaticNotebookSnapshot {
   readonly cells: readonly Protocol.Cell[];
 }
 
-/**
- * Serve a document without a server, runtime, or mutation operations.
- * Callers and readers must treat the snapshot records as immutable.
- */
-export function createStaticNotebookBackend(
-  snapshot: StaticNotebookSnapshot,
-): NotebookBackend {
-  const frames: Protocol.Event[] = [
+/** The events that describe a snapshot, in the order a host sends them. */
+function snapshotFrames(snapshot: StaticNotebookSnapshot): Protocol.Event[] {
+  return [
     {
       event: "notebook",
       data: { notebook: { ...snapshot.notebook, operations: [] } },
@@ -30,6 +25,100 @@ export function createStaticNotebookBackend(
       data: { cell },
     })),
     { event: "document", data: { document: snapshot.document } },
+  ];
+}
+
+/** A snapshot of a notebook with no cells. */
+export function emptySnapshot(notebookId: string): StaticNotebookSnapshot {
+  return {
+    notebook: {
+      id: notebookId,
+      project_id: notebookId,
+      path: null,
+      name: "",
+      updated_at: null,
+    },
+    document: {
+      notebook_id: notebookId,
+      order: [],
+      app_config: {},
+      etag: `${notebookId}:document`,
+      saved_etag: `${notebookId}:document`,
+      order_etag: `${notebookId}:order`,
+      app_config_etag: `${notebookId}:app_config`,
+      version: 1,
+    },
+    cells: [],
+  };
+}
+
+/**
+ * Show a snapshot until `live` answers.
+ *
+ * The page carries the notebook it was served with, so cells appear before
+ * the host connects. The snapshot ends in a `ready` of its own, like a
+ * static notebook's, so the replica publishes it. At the host's first sign
+ * of life a `reset` discards it, and the host's snapshot takes over. A
+ * connection that resumes from a host cursor skips the snapshot; one that
+ * resumes from the snapshot's cursor starts the host connection fresh,
+ * since the host never issued it.
+ */
+export function startWithSnapshot(
+  snapshot: StaticNotebookSnapshot,
+  live: NotebookBackend,
+): NotebookBackend {
+  const cursor = `${snapshot.notebook.id}:snapshot`;
+  return {
+    ...live,
+    transport: (attempt, handlers) => {
+      if (attempt.cursor !== null && attempt.cursor !== cursor) {
+        return live.transport(attempt, handlers);
+      }
+      if (attempt.cursor === null) {
+        for (const frame of snapshotFrames(snapshot)) {
+          if (attempt.signal.aborted) {
+            break;
+          }
+          handlers.message(frame);
+        }
+        if (attempt.signal.aborted) {
+          return Promise.resolve();
+        }
+        handlers.message({ event: "ready", id: cursor, data: {} });
+      }
+      let shown = true;
+      const discard = () => {
+        if (shown) {
+          shown = false;
+          handlers.message({ event: "reset", data: {} });
+        }
+      };
+      return live.transport(
+        { ...attempt, cursor: null },
+        {
+          open: () => {
+            discard();
+            handlers.open();
+          },
+          message: (frame) => {
+            discard();
+            handlers.message(frame);
+          },
+        },
+      );
+    },
+  };
+}
+
+/**
+ * Serve a document without a server, runtime, or mutation operations.
+ * Callers and readers must treat the snapshot records as immutable.
+ */
+export function createStaticNotebookBackend(
+  snapshot: StaticNotebookSnapshot,
+): NotebookBackend {
+  const frames: Protocol.Event[] = [
+    ...snapshotFrames(snapshot),
     { event: "ready", id: "static", data: {} },
   ];
 
@@ -75,10 +164,3 @@ export function createStaticNotebookBackend(
     },
   };
 }
-
-/** A connection that opens and delivers nothing, for static notebooks. */
-export const idle: NotebookTransport = ({ signal }, { open }) =>
-  new Promise((settle) => {
-    open();
-    signal.addEventListener("abort", () => settle(), { once: true });
-  });

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

@@ -235,6 +235,7 @@ describe("PyodideBridge.sendSave", () => {
     store.set(activeNotebookReplicaAtom, replica);
     const backend = createEditorBackend({
       static: false,
+      snapshot: null,
       transportType: "sse",
       url: () => "http://localhost/",
       headers: () => ({}),