@marimo-team/islands 0.25.3-dev5 → 0.25.3-dev51

package/src/core/cells/__tests__/error-report.test.ts

@@ -4,11 +4,51 @@
 import { describe, expect, it } from "vitest";
 import { cellId } from "@/__tests__/branded";
 import type { MarimoError } from "@/core/kernel/messages";
-import { buildErrorReport } from "../error-report";
+import { buildErrorReport, ERROR_MESSAGE_INSTRUCTIONS } from "../error-report";
 
 const CELL_ID = cellId("failed-cell");
 
 describe("buildErrorReport", () => {
+  it("preserves plain traceback text without treating angle brackets as HTML", () => {
+    const traceback =
+      '  File "<cell>", line 1\nValueError: expected <value> & got <other>';
+    expect(
+      buildErrorReport(CELL_ID, { traceback, tracebackFormat: "text" }).output,
+    ).toEqual({
+      type: "error",
+      instructions: ERROR_MESSAGE_INSTRUCTIONS,
+      message: "ValueError: expected <value> & got <other>",
+      traceback,
+    });
+  });
+  it("owns the instruction to repair the live notebook", () => {
+    const report = buildErrorReport(CELL_ID, {
+      errors: [{ type: "syntax", msg: "invalid code" }],
+    });
+    expect(report.output.instructions).toEqual("Fix this notebook error.");
+  });
+
+  it("keeps repair intent visible before oversized evidence", () => {
+    const report = buildErrorReport(CELL_ID, {
+      code: "# long code\n".repeat(10_000),
+      errors: [
+        {
+          type: "exception",
+          exception_type: "ValueError",
+          msg: "long error ".repeat(10_000),
+          raising_cell: null,
+          traceback: `<pre>Traceback\n${"long frame\n".repeat(10_000)}</pre>`,
+        },
+      ],
+    });
+    const serialized = JSON.stringify(report);
+
+    expect(serialized.length).toBeGreaterThan(8192);
+    expect(serialized.slice(0, 256)).toContain(
+      '"instructions":"Fix this notebook error."',
+    );
+  });
+
   it("retains every message and complete traceback without display limits", () => {
     const traceback = `Traceback\n${"long frame\n".repeat(10_000)}ValueError: bad <value>`;
     const errors: MarimoError[] = [
@@ -27,6 +67,7 @@ describe("buildErrorReport", () => {
       code: "failed()",
       output: {
         type: "error",
+        instructions: ERROR_MESSAGE_INSTRUCTIONS,
         message: "bad <value>\nanother error",
         traceback,
       },
@@ -49,7 +90,11 @@ describe("buildErrorReport", () => {
     ).toEqual({
       type: "cell-output",
       cell_id: CELL_ID,
-      output: { type: "error", message: "legacy error" },
+      output: {
+        type: "error",
+        instructions: ERROR_MESSAGE_INSTRUCTIONS,
+        message: "legacy error",
+      },
     });
   });
 
@@ -63,7 +108,11 @@ describe("buildErrorReport", () => {
       type: "cell-output",
       cell_id: CELL_ID,
       code: "",
-      output: { type: "error", message: "invalid code" },
+      output: {
+        type: "error",
+        instructions: ERROR_MESSAGE_INSTRUCTIONS,
+        message: "invalid code",
+      },
     });
   });
 
@@ -80,6 +129,7 @@ describe("buildErrorReport", () => {
       cell_id: CELL_ID,
       output: {
         type: "error",
+        instructions: ERROR_MESSAGE_INSTRUCTIONS,
         message: "first\nsecond",
         traceback:
           "Traceback\nValueError: first\n\nTraceback\nValueError: second",

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/__tests__/session.test.ts

@@ -174,8 +174,11 @@ describe("notebookStateFromSession", () => {
         channel: "marimo-error",
         data: [
           {
-            type: "unknown",
+            type: "exception",
+            exception_type: "ValueError",
             msg: "Something went wrong",
+            raising_cell: null,
+            traceback: "Traceback line 1",
           },
         ],
         mimetype: "application/vnd.marimo+error",
@@ -201,8 +204,9 @@ describe("notebookStateFromSession", () => {
             {
               type: "stream",
               name: "stderr",
-              text: "<pre>ValueError: cached failure</pre>",
+              text: "ValueError: cached <failure>",
               mimetype: "application/vnd.marimo+traceback",
+              traceback_format: "text",
               code,
             },
           ],
@@ -212,9 +216,20 @@ describe("notebookStateFromSession", () => {
       invariant(state, "state is null");
       expect(state.cellRuntime[CELL_1].output).toMatchObject({
         code,
-        data: [{ type: "unknown", msg: "cached failure" }],
+        data: [
+          {
+            type: "exception",
+            exception_type: "ValueError",
+            msg: "cached failure",
+            traceback: "Traceback\nValueError: cached failure",
+          },
+        ],
       });
       expect(state.cellRuntime[CELL_1].consoleOutputs[0].code).toBe(code);
+      expect(state.cellRuntime[CELL_1].consoleOutputs[0]).toMatchObject({
+        traceback_format: "text",
+        data: "ValueError: cached <failure>",
+      });
     });
 
     it("handles data output in session cell", () => {

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/error-report.ts

@@ -6,26 +6,29 @@ import { sanitizeHtml } from "@/plugins/core/sanitize-html";
 import { parseHtmlContent } from "@/utils/dom";
 import type { CellId } from "./ids";
 
-export interface CellOutputHandoff<Output> {
+export interface CellOutputMessage<Output> {
   type: "cell-output";
   cell_id: CellId;
   code?: string;
   output: Output;
 }
 
-export interface ErrorHandoffOutput {
+export interface ErrorMessageOutput {
   type: "error";
+  instructions: string;
   message: string;
   traceback?: string;
 }
 
+export const ERROR_MESSAGE_INSTRUCTIONS = "Fix this notebook error.";
+
 export function buildErrorReport(
   cellId: CellId,
   evidence: { code?: string } & (
     | { errors: MarimoError[] }
-    | { traceback: string }
+    | { traceback: string; tracebackFormat: "html" | "text" }
   ),
-): CellOutputHandoff<ErrorHandoffOutput> {
+): CellOutputMessage<ErrorMessageOutput> {
   let message: string;
   let traceback: string;
   if ("errors" in evidence) {
@@ -38,18 +41,23 @@ export function buildErrorReport(
       )
       .join("\n\n");
   } else {
-    traceback = parseHtmlContent(sanitizeHtml(evidence.traceback));
+    traceback =
+      evidence.tracebackFormat === "html"
+        ? parseHtmlContent(sanitizeHtml(evidence.traceback))
+        : evidence.traceback;
     message = traceback.split("\n").findLast((line) => line.length > 0) ?? "";
   }
 
+  // Put repair intent before evidence so it survives prefix truncation.
   return {
     type: "cell-output",
     cell_id: cellId,
-    ...(evidence.code === undefined ? {} : { code: evidence.code }),
     output: {
       type: "error",
+      instructions: ERROR_MESSAGE_INSTRUCTIONS,
       message,
       ...(traceback ? { traceback } : {}),
     },
+    ...(evidence.code === undefined ? {} : { code: evidence.code }),
   };
 }

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/cells/session.ts

@@ -206,8 +206,20 @@ function createCellRuntimeFromSession(
         channel: "marimo-error",
         data: [
           {
-            type: "unknown",
+            type: "exception",
+            exception_type: primaryOutput.ename,
             msg: primaryOutput.evalue,
+            raising_cell: null,
+            traceback:
+              primaryOutput.traceback.length === 0
+                ? null
+                : primaryOutput.traceback
+                    .map((line, index, lines) =>
+                      index < lines.length - 1 && !line.endsWith("\n")
+                        ? `${line}\n`
+                        : line,
+                    )
+                    .join(""),
           },
         ],
         mimetype: "application/vnd.marimo+error",
@@ -240,6 +252,9 @@ function createCellRuntimeFromSession(
           channel: "media",
           data: consoleOutput.data,
           mimetype: consoleOutput.mimetype,
+          ...(consoleOutput.traceback_format === undefined
+            ? {}
+            : { traceback_format: consoleOutput.traceback_format }),
           timestamp: DEFAULT_TIMESTAMP,
           ...(consoleOutput.code === undefined
             ? {}
@@ -251,6 +266,9 @@ function createCellRuntimeFromSession(
         channel: consoleOutput.name === "stderr" ? "stderr" : "stdout",
         data: consoleOutput.text,
         mimetype: consoleOutput.mimetype ?? "text/plain",
+        ...(consoleOutput.traceback_format === undefined
+          ? {}
+          : { traceback_format: consoleOutput.traceback_format }),
         timestamp: DEFAULT_TIMESTAMP,
         ...(consoleOutput.code === undefined
           ? {}

package/src/core/config/pair.ts

@@ -3,16 +3,18 @@
 import { atom } from "jotai";
 import { z } from "zod";
 
-export const pairPreviewSchema = z.object({
+export const pairConfigSchema = z.object({
   command: z.string(),
+  hostEnabled: z.boolean().default(false),
   templates: z.object({
     prompt: z.string(),
+    notebook: z.string(),
     session: z.string(),
     token_file: z.string(),
     token: z.string(),
   }),
 });
 
-export type PairPreviewConfig = z.infer<typeof pairPreviewSchema>;
+export type PairConfig = z.infer<typeof pairConfigSchema>;
 
-export const pairPreviewAtom = atom<PairPreviewConfig | undefined>(undefined);
+export const pairConfigAtom = atom<PairConfig | undefined>(undefined);

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]]);
+  });
+});

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

@@ -0,0 +1,126 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { describe, expect, it } from "vitest";
+import type * as Protocol from "@marimo-team/client/protocol";
+import { document } from "../resources/document";
+import { createReducer } from "@marimo-team/client/reducer";
+import { fixtureEvents } from "./fixtures";
+
+const reducer = createReducer({ document });
+const snapshot = fixtureEvents("notebook-events.sse");
+const edits = fixtureEvents("edits.sse");
+
+function replay(
+  events: readonly Protocol.EventOutput[],
+  from = reducer.initial,
+) {
+  return events.reduce((state, event) => reducer.reduce(state, event), from);
+}
+
+const confirmed = () => replay(snapshot);
+const current = (state: ReturnType<typeof replay>) =>
+  state.resources.document.current;
+
+describe("document resource", () => {
+  it("publishes the snapshot at ready, then each completed edit and save", () => {
+    const ready = snapshot.findIndex((event) => event.event === "ready");
+    const opening = replay(snapshot.slice(0, ready));
+    expect(current(opening)).toBeNull();
+    const first = current(replay(snapshot.slice(ready), opening));
+    expect(first?.revision.order).toEqual(["c1", "c3", "k7f2"]);
+    expect([...first!.cells.keys()]).toEqual(first?.revision.order);
+
+    const [edit, save] = edits.filter((event) => event.event === "document");
+    const pending = replay(
+      edits.filter((event) => event.event !== "document"),
+      confirmed(),
+    );
+    expect(current(pending)).toEqual(first);
+    const changed = reducer.reduce(pending, edit);
+    expect(current(changed)?.revision).toEqual(edit.data.document);
+    expect([...current(changed)!.cells.keys()].toSorted()).toEqual(
+      edit.data.document.order.toSorted(),
+    );
+    const saved = current(reducer.reduce(changed, save));
+    expect(saved?.revision).toEqual(save.data.document);
+    expect(saved?.cells.get("c3")?.code).toBe("x = 22");
+    expect(saved?.cells.has("k7f2")).toBe(false);
+    expect(saved?.revision.saved_etag).toBe(saved?.revision.etag);
+    expect(first?.cells.get("c3")?.code).toBe("x = 21");
+    expect(first?.cells.has("k7f2")).toBe(true);
+  });
+
+  it("applies order-only changes and distinguishes an empty notebook from no document", () => {
+    const state = confirmed();
+    const revision = current(state)!.revision;
+    const reordered = {
+      ...revision,
+      order: revision.order.toReversed(),
+      version: revision.version + 1,
+    };
+    const changed = reducer.reduce(state, {
+      event: "document",
+      data: { document: reordered },
+      id: "200",
+    });
+    expect(current(changed)).toEqual({
+      revision: reordered,
+      cells: current(state)?.cells,
+    });
+
+    const empty = { ...revision, order: [] };
+    const opening = reducer.reduce(reducer.initial, {
+      event: "document",
+      data: { document: empty },
+    });
+    expect(current(opening)).toBeNull();
+    expect(
+      current(reducer.reduce(opening, { event: "ready", data: {}, id: "0" })),
+    ).toEqual({ revision: empty, cells: new Map() });
+    expect(
+      current(
+        reducer.reduce(reducer.initial, { event: "ready", data: {}, id: "0" }),
+      ),
+    ).toBeNull();
+  });
+
+  it("keeps the document while a live update is pending and after a replay completes it", () => {
+    const state = confirmed();
+    const [cell, , removed, published] = edits;
+    if (published.event !== "document") {
+      throw new Error("Fixture does not publish a document");
+    }
+    const partial = replay([cell, removed], state);
+    expect(current(partial)).toBe(current(state));
+    const completed = replay(
+      [published, { event: "ready", data: {}, id: "113" }],
+      partial,
+    );
+    expect(current(completed)?.revision).toEqual(published.data.document);
+  });
+
+  it("removes a notebook without waiting for individual cell removals", () => {
+    const removed = reducer.reduce(confirmed(), {
+      event: "notebook.removed",
+      data: { id: "n1", time: "2026-10-01T09:30:00Z" },
+      id: "200",
+    });
+    expect(current(removed)).toBeNull();
+  });
+
+  it("rejects records that cannot form a complete revision", () => {
+    const state = confirmed();
+    const revision = current(state)!.revision;
+    expect(() =>
+      reducer.reduce(state, {
+        event: "document",
+        data: { document: { ...revision, order: ["missing"] } },
+        id: "200",
+      }),
+    ).toThrow("Document records do not match");
+    const partial = reducer.reduce(state, edits[0]);
+    expect(() =>
+      reducer.reduce(partial, { event: "ready", data: {}, id: "200" }),
+    ).toThrow("incomplete document update");
+  });
+});