@marimo-team/islands 0.25.3-dev24 → 0.25.3-dev245

package/src/core/cells/session.ts

@@ -1,17 +1,19 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
+/** Read the notebook a page was served with: its cells as a host snapshot, and their outputs. */
+
+import type * as Protocol from "@marimo-team/client/protocol";
 import type * as api from "@marimo-team/marimo-api";
 import { mergeArray } from "@/utils/edit-distance";
-import { MultiColumn } from "@/utils/id-tree";
 import { Logger } from "@/utils/Logger";
 import { parseOutline } from "../dom/outline";
-import type { NotebookState } from "./cells";
+import type { StaticNotebookSnapshot } from "../transports/static";
 import { CellId, SETUP_CELL_ID } from "./ids";
-import {
-  type CellData,
-  type CellRuntimeState,
-  createCellRuntimeState,
-} from "./types";
+import { DEFAULT_CELL_NAME } from "./names";
+import { type CellRuntimeState, createCellRuntimeState } from "./types";
+
+/** The identity of a snapshot the page carries. A host's own stream replaces it. */
+const EMBEDDED = "embedded";
 
 // Constants
 const DEFAULT_TIMESTAMP = 0;
@@ -56,7 +58,7 @@ function mergeSessionAndNotebookCells(
     return {
       cellIds,
       sessionCellData: new Map(
-        cellIds.map((id, idx) => [id, null] as [CellId, SessionCell | null]),
+        cellIds.map((id) => [id, null] as [CellId, SessionCell | null]),
       ),
       notebookCellData: new Map(
         cellIds.map(
@@ -143,7 +145,7 @@ function createEmptyNotebookCell(): NotebookCell {
   return {
     id: CellId.create(),
     name: EMPTY_STRING,
-    code: EMPTY_STRING,
+    code: null,
     code_hash: null,
     config: {
       column: null,
@@ -163,24 +165,22 @@ function createEmptySessionCell(): SessionCell {
   };
 }
 
-function createCellDataFromNotebook(
-  cellId: CellId,
-  notebookCell: NotebookCell,
-): CellData {
+/** The cell as a host would describe it. A snapshot never changes, so its etags only need to be distinct. */
+function cellRecord(cellId: CellId, cell: NotebookCell): Protocol.Cell {
   return {
     id: cellId,
-    name: notebookCell.name ?? EMPTY_STRING,
-    code: notebookCell.code ?? EMPTY_STRING,
-    edited: false,
-    lastCodeRun: null,
-    lastExecutionTime: null,
+    notebook_id: EMBEDDED,
+    code: cell.code,
+    name: cell.name || DEFAULT_CELL_NAME,
     config: {
-      column: notebookCell.config?.column ?? null,
-      disabled: notebookCell.config?.disabled ?? false,
-      hide_code: notebookCell.config?.hide_code ?? false,
-      expand_output: notebookCell.config?.expand_output ?? false,
+      column: cell.config?.column ?? null,
+      disabled: cell.config?.disabled ?? false,
+      hide_code: cell.config?.hide_code ?? false,
+      expand_output: cell.config?.expand_output ?? false,
     },
-    serializedEditorState: null,
+    etag: `${EMBEDDED}:${cellId}`,
+    code_fingerprint: cell.code_hash ?? `${EMBEDDED}:${cellId}:code`,
+    version: 1,
   };
 }
 
@@ -278,45 +278,68 @@ function createCellRuntimeFromSession(
   };
 }
 
-export function notebookStateFromSession(
-  session: api.Session["NotebookSessionV1"] | null | undefined,
-  notebook: api.Notebook["NotebookV1"] | null | undefined,
-): NotebookState | null {
-  // Merge session and notebook cells using edit distance
+/**
+ * Read the session and notebook a page embeds.
+ *
+ * The cells become a host snapshot the replica starts from, and the session's
+ * outputs seed each cell's runtime until the kernel speaks. Null when the page
+ * carries no cells.
+ */
+export function readExport({
+  session,
+  notebook,
+  filename,
+  appConfig,
+}: {
+  session: api.Session["NotebookSessionV1"] | null | undefined;
+  notebook: api.Notebook["NotebookV1"] | null | undefined;
+  filename: string | null;
+  appConfig: Record<string, unknown>;
+}): {
+  snapshot: StaticNotebookSnapshot | null;
+  cellRuntime: Record<CellId, CellRuntimeState>;
+} {
   const { cellIds, sessionCellData, notebookCellData } =
     mergeSessionAndNotebookCells(session, notebook);
-
   if (cellIds.length === 0) {
-    return null;
+    return { snapshot: null, cellRuntime: {} };
   }
 
-  const cellData: Record<CellId, CellData> = {};
+  const cells: Protocol.Cell[] = [];
   const cellRuntime: Record<CellId, CellRuntimeState> = {};
-
-  // Process each cell
   for (const cellId of cellIds) {
-    const sessionCell = sessionCellData.get(cellId);
-    const notebookCell = notebookCellData.get(cellId);
-
-    // Create cell data from notebook if available
-    if (notebookCell) {
-      cellData[cellId] = createCellDataFromNotebook(cellId, notebookCell);
-    }
-
-    // Create cell runtime
-    // This needs always be created even if there is no session cell
-    // in order to display the cell in the correct state
-    cellRuntime[cellId] = createCellRuntimeFromSession(sessionCell);
+    cells.push(
+      cellRecord(
+        cellId,
+        notebookCellData.get(cellId) ?? createEmptyNotebookCell(),
+      ),
+    );
+    cellRuntime[cellId] = createCellRuntimeFromSession(
+      sessionCellData.get(cellId),
+    );
   }
 
   return {
-    cellIds: MultiColumn.from([cellIds]),
-    cellData: cellData,
-    cellRuntime: cellRuntime,
-    cellHandles: {},
-    history: [],
-    scrollKey: null,
-    cellLogs: [],
-    untouchedNewCells: new Set(),
+    snapshot: {
+      notebook: {
+        id: EMBEDDED,
+        project_id: EMBEDDED,
+        path: filename,
+        name: filename ?? EMPTY_STRING,
+        updated_at: null,
+      },
+      document: {
+        notebook_id: EMBEDDED,
+        order: cellIds,
+        app_config: appConfig,
+        etag: `${EMBEDDED}:document`,
+        saved_etag: `${EMBEDDED}:document`,
+        order_etag: `${EMBEDDED}:order`,
+        app_config_etag: `${EMBEDDED}:app_config`,
+        version: 1,
+      },
+      cells,
+    },
+    cellRuntime,
   };
 }

package/src/core/cells/types.ts

@@ -1,13 +1,24 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
 import type { Milliseconds, Seconds } from "@/utils/time";
-import type { SerializedEditorState } from "../codemirror/types";
 import type { OutputMessage } from "../kernel/messages";
 import type { CellConfig, RuntimeState } from "../network/types";
 import type { CellId } from "./ids";
 import { DEFAULT_CELL_NAME } from "./names";
 import type { Outline } from "./outline";
 
+/**
+ * Whether a cell's code has changed since it last ran. A cell that never ran
+ * is edited once it has code. Whitespace at the ends does not count.
+ *
+ * TODO(MO-8028): Temporary until staleness comes from the host's executions.
+ */
+export function isEdited(lastCodeRun: string | null, code: string): boolean {
+  return lastCodeRun === null
+    ? code.trim().length > 0
+    : lastCodeRun.trim() !== code.trim();
+}
+
 /**
  * Create a new cell with default state.
  */
@@ -19,7 +30,6 @@ export function createCell({
   lastExecutionTime = null,
   edited = false,
   config,
-  serializedEditorState = null,
 }: Partial<CellData> & { id: CellId }): CellData {
   return {
     id: id,
@@ -34,7 +44,6 @@ export function createCell({
     edited: edited,
     lastCodeRun: lastCodeRun,
     lastExecutionTime: lastExecutionTime,
-    serializedEditorState: serializedEditorState,
   };
 }
 
@@ -85,8 +94,6 @@ export interface CellData {
   lastExecutionTime: number | null;
   /** cell configuration */
   config: CellConfig;
-  /** serialized state of the underlying editor */
-  serializedEditorState: SerializedEditorState | null;
 }
 
 export interface CellRuntimeState {
@@ -95,7 +102,7 @@ export interface CellRuntimeState {
   /** TOC outline */
   outline: Outline | null;
   /** messages encoding the cell's console outputs. */
-  consoleOutputs: WithResponse<OutputMessage>[];
+  consoleOutputs: ConsoleOutputMessage[];
   /** current status of the cell */
   status: RuntimeState;
   /** whether the cell has stale inputs*/
@@ -130,3 +137,12 @@ export type WithResponse<T> = T & {
    */
   response?: string;
 };
+
+/**
+ * A console output as held by the frontend. The id is assigned when the
+ * output arrives and never changes, so it can identify the output while
+ * neighboring outputs collapse, truncate, or receive a stdin response.
+ */
+export type ConsoleOutputMessage = WithResponse<OutputMessage> & {
+  id?: number;
+};

package/src/core/cells/utils.ts

@@ -25,7 +25,7 @@ export function notebookNeedsRun(state: NotebookState) {
 }
 
 export function notebookCells(state: NotebookState) {
-  return state.cellIds.inOrderIds.map((cellId) => state.cellData[cellId]);
+  return state.cellIds.map((cellId) => state.cellData[cellId]);
 }
 
 export function notebookCellEditorViews({ cellHandles }: NotebookState) {
@@ -42,7 +42,7 @@ export function notebookCellEditorViews({ cellHandles }: NotebookState) {
 export function disabledCellIds(state: NotebookState) {
   const { cellIds, cellData } = state;
   const disabledCells: CellId[] = [];
-  for (const cellId of cellIds.inOrderIds) {
+  for (const cellId of cellIds) {
     const cell = cellData[cellId];
     if (cell.config.disabled) {
       disabledCells.push(cellId);
@@ -54,7 +54,7 @@ export function disabledCellIds(state: NotebookState) {
 export function enabledCellIds(state: NotebookState) {
   const { cellIds, cellData } = state;
   const enabledCells: CellId[] = [];
-  for (const cellId of cellIds.inOrderIds) {
+  for (const cellId of cellIds) {
     const cell = cellData[cellId];
     if (!cell.config.disabled) {
       enabledCells.push(cellId);
@@ -79,11 +79,13 @@ export function getUndoLabel(state: NotebookState): string {
 }
 
 /**
- * Get the status of the descendants of the given cell.
+ * Summarize the run state of the given descendants, whether any is stale,
+ * errored, or running.
  */
-export function getDescendantsStatus(state: NotebookState, cellId: CellId) {
-  const column = state.cellIds.findWithId(cellId);
-  const descendants = column.getDescendants(cellId);
+export function getDescendantsStatus(
+  state: NotebookState,
+  descendants: readonly CellId[],
+) {
   const stale = descendants.some(
     (id) => state.cellRuntime[id]?.staleInputs || state.cellData[id]?.edited,
   );
@@ -106,7 +108,7 @@ export function getDescendantsStatus(state: NotebookState, cellId: CellId) {
  */
 export function staleCellIds(state: NotebookState) {
   const { cellIds, cellData, cellRuntime } = state;
-  return cellIds.inOrderIds.filter(
+  return cellIds.filter(
     (cellId) =>
       isUninstantiated({
         // runElapstedTimeMs is what we've seen in this session

package/src/core/codemirror/__tests__/format.test.ts

@@ -17,7 +17,6 @@ import { OverridingHotkeyProvider } from "@/core/hotkeys/hotkeys";
 import { requestClientAtom } from "@/core/network/requests";
 import type { MarimoConfig } from "@/core/network/types";
 import { store } from "@/core/state/jotai";
-import { type CodemirrorCellActions, cellActionsState } from "../cells/state";
 import { cellIdState } from "../config/extension";
 import { formatAll, formatEditorViews, formatSQL } from "../format";
 import {
@@ -44,7 +43,6 @@ vi.mock("@/core/config/config", () => ({
   }),
 }));
 
-const updateCellCode = vi.fn();
 const createdViews: EditorView[] = [];
 
 function createEditor(content: string, cellId: CellId) {
@@ -65,9 +63,6 @@ function createEditor(content: string, cellId: CellId) {
         lspConfig: {},
       }),
       cellIdState.of(cellId),
-      cellActionsState.of({
-        updateCellCode,
-      } as unknown as CodemirrorCellActions),
     ],
   });
 
@@ -85,7 +80,6 @@ const mockConfig = {
 } as MarimoConfig;
 
 beforeEach(() => {
-  updateCellCode.mockClear();
   vi.clearAllMocks();
   // Set the mock request client in the atom
   store.set(requestClientAtom, mockRequestClient);
@@ -131,16 +125,6 @@ describe("format", () => {
 
       expect(views[cid1].state.doc.toString()).toBe(formattedCode1);
       expect(views[cid2].state.doc.toString()).toBe(formattedCode2);
-      expect(updateCellCode).toHaveBeenCalledWith({
-        cellId: cid1,
-        code: formattedCode1,
-        formattingChange: true,
-      });
-      expect(updateCellCode).toHaveBeenCalledWith({
-        cellId: cid2,
-        code: formattedCode2,
-        formattingChange: true,
-      });
     });
 
     it("should not update editor if formatted code is same as original", async () => {
@@ -161,7 +145,6 @@ describe("format", () => {
       await formatEditorViews(views);
 
       expect(views[cid].state.doc.toString()).toBe(originalCode);
-      expect(updateCellCode).not.toHaveBeenCalled();
     });
   });
 
@@ -194,12 +177,6 @@ describe("format", () => {
         },
         lineLength: 88,
       });
-
-      expect(updateCellCode).toHaveBeenCalledWith({
-        cellId: cid1,
-        code: "import numpy as np",
-        formattingChange: true,
-      });
     });
   });
 
@@ -220,11 +197,6 @@ describe("format", () => {
         WHERE
           id = 1"
       `);
-      expect(updateCellCode).toHaveBeenCalledWith({
-        cellId: cid,
-        code: editor.state.doc.toString(),
-        formattingChange: true,
-      });
     });
 
     it("should not format if language adapter is not SQL", async () => {
@@ -238,7 +210,6 @@ describe("format", () => {
       expect(editor.state.doc.toString()).toBe(
         "SELECT * FROM table WHERE id = 1",
       );
-      expect(updateCellCode).not.toHaveBeenCalled();
     });
   });
 
@@ -257,10 +228,5 @@ describe("format", () => {
       WHERE
         id = 1"
     `);
-    expect(updateCellCode).toHaveBeenCalledWith({
-      cellId: cid,
-      code: editor.state.doc.toString(),
-      formattingChange: true,
-    });
   });
 });

package/src/core/codemirror/__tests__/setup.test.ts

@@ -100,7 +100,7 @@ function getDuplicateKeymaps(state: EditorState) {
     (keymap) => keymap,
   );
   const duplicates = Objects.fromEntries(
-    Object.entries(groupBy).filter(([key, value]) => value.length > 1),
+    Object.entries(groupBy).filter(([_key, value]) => value.length > 1),
   );
   return duplicates;
 }
@@ -198,22 +198,22 @@ test("go to definition falls through to lower-priority LSP keymap", () => {
 test("placeholder adds another extension", () => {
   const opts = getOpts();
   const withAI = new PythonLanguageAdapter()
-    .getExtension(
-      opts.cellId,
-      opts.completionConfig,
-      opts.hotkeys,
-      "marimo-import",
-      opts.lspConfig,
-    )
+    .getExtension({
+      cellId: opts.cellId,
+      completionConfig: opts.completionConfig,
+      hotkeys: opts.hotkeys,
+      placeholderType: "marimo-import",
+      lspConfig: opts.lspConfig,
+    })
     .flat();
   const withoutAI = new PythonLanguageAdapter()
-    .getExtension(
-      opts.cellId,
-      opts.completionConfig,
-      opts.hotkeys,
-      "none",
-      opts.lspConfig,
-    )
+    .getExtension({
+      cellId: opts.cellId,
+      completionConfig: opts.completionConfig,
+      hotkeys: opts.hotkeys,
+      placeholderType: "none",
+      lspConfig: opts.lspConfig,
+    })
     .flat();
   expect(withAI.length - 1).toBe(withoutAI.length);
 });
@@ -221,22 +221,22 @@ test("placeholder adds another extension", () => {
 test("ai adds more extensions", () => {
   const opts = getOpts();
   const withAI = new PythonLanguageAdapter()
-    .getExtension(
-      opts.cellId,
-      opts.completionConfig,
-      opts.hotkeys,
-      "ai",
-      opts.lspConfig,
-    )
+    .getExtension({
+      cellId: opts.cellId,
+      completionConfig: opts.completionConfig,
+      hotkeys: opts.hotkeys,
+      placeholderType: "ai",
+      lspConfig: opts.lspConfig,
+    })
     .flat();
   const withoutAI = new PythonLanguageAdapter()
-    .getExtension(
-      opts.cellId,
-      opts.completionConfig,
-      opts.hotkeys,
-      "none",
-      opts.lspConfig,
-    )
+    .getExtension({
+      cellId: opts.cellId,
+      completionConfig: opts.completionConfig,
+      hotkeys: opts.hotkeys,
+      placeholderType: "none",
+      lspConfig: opts.lspConfig,
+    })
     .flat();
   expect(withAI.length - 2).toBe(withoutAI.length);
 });

package/src/core/codemirror/ai/__tests__/resources.test.ts

@@ -0,0 +1,117 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { markdownLanguage } from "@codemirror/lang-markdown";
+import { hoverResource, type Resource } from "@marimo-team/codemirror-mcp";
+import { createStore } from "jotai";
+import { assert, beforeEach, describe, expect, it, vi } from "vitest";
+import { MockNotebook } from "@/__mocks__/notebook";
+import { getAIContextRegistry } from "@/core/ai/context/context";
+import { ErrorContextProvider } from "@/core/ai/context/providers/error";
+import { AIContextRegistry } from "@/core/ai/context/registry";
+import { notebookAtom } from "@/core/cells/cells";
+import { CellId } from "@/core/cells/ids";
+import { resourceExtension } from "../resources";
+
+vi.mock("@marimo-team/codemirror-mcp", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@marimo-team/codemirror-mcp")>()),
+  hoverResource: vi.fn(() => []),
+}));
+
+vi.mock("@/core/ai/context/context", () => ({
+  getAIContextRegistry: vi.fn(),
+}));
+
+describe("resource tooltips", () => {
+  const message = '<b>Unexpected response</b> &amp; "details"';
+  let provider: ErrorContextProvider;
+  let resource: Resource;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    const store = createStore();
+    store.set(
+      notebookAtom,
+      MockNotebook.notebookStateWithErrors([
+        {
+          cellId: CellId.create(),
+          cellName: "Cell 1",
+          errorData: [MockNotebook.errors.exception(message)],
+        },
+      ]),
+    );
+    provider = new ErrorContextProvider(store);
+    resource = provider.getItems()[1];
+    vi.mocked(getAIContextRegistry).mockReturnValue(
+      new AIContextRegistry().register(provider),
+    );
+    resourceExtension({ language: markdownLanguage, store });
+  });
+
+  function renderTooltip(item = resource) {
+    const options = vi.mocked(hoverResource).mock.calls[0][0];
+    assert(options.createTooltip);
+    return options.createTooltip(item).dom;
+  }
+
+  it("preserves literal text in cell error descriptions", () => {
+    const dom = renderTooltip();
+    expect(dom.textContent).toBe(message);
+    expect(dom.childElementCount).toBe(0);
+  });
+
+  it("preserves literal descriptions when a provider is unavailable", () => {
+    const dom = renderTooltip({ ...resource, type: "unknown" });
+    expect(dom.textContent).toBe(message);
+    expect(dom.childElementCount).toBe(0);
+  });
+
+  it("falls back to the literal resource name", () => {
+    const dom = renderTooltip({
+      ...resource,
+      description: undefined,
+      name: message,
+    });
+    expect(dom.textContent).toBe(message);
+    expect(dom.childElementCount).toBe(0);
+  });
+
+  it("preserves literal text in completion info strings", () => {
+    vi.spyOn(provider, "formatCompletion").mockReturnValue({
+      label: "Error",
+      info: message,
+    });
+    const dom = renderTooltip({ ...resource, description: "Fallback" });
+    expect(dom.textContent).toBe(message);
+    expect(dom.childElementCount).toBe(0);
+  });
+
+  it("preserves literal fallback text when an info renderer returns null", () => {
+    vi.spyOn(provider, "formatCompletion").mockReturnValue({
+      label: "Error",
+      info: () => null,
+    });
+    const dom = renderTooltip();
+    expect(dom.textContent).toBe(message);
+    expect(dom.childElementCount).toBe(0);
+  });
+
+  it("preserves literal fallback text for async info renderers", () => {
+    vi.spyOn(provider, "formatCompletion").mockReturnValue({
+      label: "Error",
+      info: async () => document.createElement("div"),
+    });
+    const dom = renderTooltip();
+    expect(dom.textContent).toBe(message);
+    expect(dom.childElementCount).toBe(0);
+  });
+
+  it.each(["element", "tooltip"])("preserves custom %s renderers", (kind) => {
+    const dom = document.createElement("strong");
+    dom.textContent = "Details";
+    vi.spyOn(provider, "formatCompletion").mockReturnValue({
+      label: "Error",
+      info: () => (kind === "element" ? dom : { dom }),
+    });
+    expect(renderTooltip()).toBe(dom);
+  });
+});

package/src/core/codemirror/ai/resources.ts

@@ -142,7 +142,7 @@ export function resourceExtension(opts: {
 
 function asDom(value: string): TooltipView {
   const tooltip = document.createElement("div");
-  tooltip.innerHTML = value;
+  tooltip.textContent = value;
   return {
     dom: tooltip,
   };

package/src/core/codemirror/cells/__tests__/extensions.test.ts

@@ -8,7 +8,6 @@ import {
 } from "@codemirror/state";
 import { describe, expect, it } from "vitest";
 import { formattingChangeEffect } from "../../format";
-import { loroSyncAnnotation } from "../../rtc/loro/sync";
 import { exportedForTesting } from "../extensions";
 
 const { shouldAutorunMarkdownUpdate } = exportedForTesting;
@@ -50,13 +49,10 @@ describe("shouldAutorunMarkdownUpdate", () => {
     ).toBe(false);
   });
 
-  it("ignores RTC sync transactions", () => {
+  it("ignores remote transactions while focused", () => {
     const transaction = createTransaction({
       changes: { from: 0, insert: "#" },
-      annotations: [
-        Transaction.userEvent.of("input.type"),
-        loroSyncAnnotation.of(true),
-      ],
+      annotations: [Transaction.remote.of(true)],
     });
 
     expect(