@marimo-team/islands 0.25.3-dev2 → 0.25.3-dev200

package/src/core/cells/columns.ts

@@ -0,0 +1,38 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/** How a document's cells fall into columns. */
+
+import type { EditableDocument } from "@/core/notebook/document";
+import type { CellId } from "./ids";
+
+/**
+ * Each cell's column: its `column` config, or the column of the cell before
+ * it. The first cell starts in column 0.
+ */
+export function resolveColumns(
+  document: EditableDocument,
+): Map<CellId, number> {
+  const columns = new Map<CellId, number>();
+  let current = 0;
+  for (const id of document.order) {
+    const column = document.cells.get(id)?.config.column;
+    if (column != null && column >= 0) {
+      current = column;
+    }
+    // The protocol's ids are plain strings; the notebook brands them.
+    columns.set(id as CellId, current);
+  }
+  return columns;
+}
+
+/** The cells of each column in order, with empty columns for gaps. */
+export function groupByColumn(document: EditableDocument): CellId[][] {
+  const columns: CellId[][] = [[]];
+  for (const [id, column] of resolveColumns(document)) {
+    while (columns.length <= column) {
+      columns.push([]);
+    }
+    columns[column].push(id);
+  }
+  return columns;
+}

package/src/core/cells/document.ts

@@ -0,0 +1,289 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/**
+ * Keep the notebook state and the host document in step while cells live
+ * in both.
+ *
+ * TODO(MO-8028): Delete this module once components read cells from the
+ * document model and `notebookAtom` holds only runtime and editor state.
+ */
+
+import { dequal as isEqual } from "dequal";
+import type { createStore } from "jotai";
+import { createRef, type RefObject } from "react";
+import type { CellHandle } from "@/components/editor/notebook-cell";
+import type {
+  DocumentEdit,
+  DocumentEditor,
+  DocumentModel,
+  EditableCell,
+  EditableDocument,
+} from "@/core/notebook/document";
+import type { DispatchedActionOf } from "@/utils/createReducer";
+import { prepareCellCodeUpdate } from "../codemirror/language/cell-code";
+import { canUseRtc, isRtcEnabled } from "../rtc/state";
+import { store } from "../state/jotai";
+import { activeDocumentModelAtom } from "../session/active-notebook";
+import type { NotebookState, ReducerCellActions } from "./cells";
+import type { CellId } from "./ids";
+import { followColumnsAtom } from "./layout";
+import {
+  type CellData,
+  createCell,
+  createCellConfig,
+  createCellRuntimeState,
+  isEdited,
+} from "./types";
+
+type CellAction = DispatchedActionOf<ReducerCellActions>;
+
+// Following the document ----------------------------------------------------
+
+/** The cell's data with the document's fields, and its editor brought along. */
+function followCell(
+  current: CellData,
+  cell: EditableCell,
+  handle: RefObject<CellHandle | null> | undefined,
+): CellData {
+  // Withheld source keeps the code this client has.
+  const code = cell.code ?? current.code;
+  const config = isEqual(current.config, cell.config)
+    ? current.config
+    : createCellConfig(cell.config);
+  if (
+    code === current.code &&
+    cell.name === current.name &&
+    config === current.config
+  ) {
+    return current;
+  }
+  if (code === current.code) {
+    return { ...current, name: cell.name, config };
+  }
+  // RTC cells follow Loro. Other editors take the host's code; one that
+  // shows it already, as the editor this client types in does, is left alone.
+  if (!isRtcEnabled() || !canUseRtc(current.id)) {
+    const view = handle?.current?.editorViewOrNull;
+    const update = view && prepareCellCodeUpdate(view.state, code);
+    if (update) {
+      view.dispatch(update);
+    }
+  }
+  return {
+    ...current,
+    code,
+    name: cell.name,
+    config,
+    edited: isEdited(current.lastCodeRun, code),
+  };
+}
+
+/**
+ * Make the notebook's cells and order follow the document.
+ *
+ * Returns the same state when nothing differs, so a local edit that the
+ * document already reflects changes nothing.
+ *
+ * TODO(MO-8028): Delete with `reconcileDocument` once cells are read from
+ * the document model.
+ */
+export function applyDocument(
+  state: NotebookState,
+  document: EditableDocument,
+): NotebookState {
+  // The protocol's ids are plain strings; the notebook brands them.
+  const cellIds = isEqual(document.order, state.cellIds)
+    ? state.cellIds
+    : ([...document.order] as CellId[]);
+  let { cellData, cellRuntime, cellHandles } = state;
+  for (const id of cellIds) {
+    const cell = document.cells.get(id);
+    const current = state.cellData[id];
+    if (cell === undefined) {
+      continue;
+    }
+    if (current === undefined) {
+      // A new cell with code is stale until it runs. The kernel's last run
+      // settles it on kernel-ready.
+      const code = cell.code ?? "";
+      cellData = {
+        ...cellData,
+        [id]: createCell({
+          id,
+          code,
+          name: cell.name,
+          config: createCellConfig(cell.config),
+          edited: code.trim().length > 0,
+        }),
+      };
+      cellRuntime = {
+        ...cellRuntime,
+        [id]: cellRuntime[id] ?? createCellRuntimeState(),
+      };
+      cellHandles = { ...cellHandles, [id]: createRef() };
+      continue;
+    }
+    const next = followCell(current, cell, state.cellHandles[id]);
+    if (next !== current) {
+      cellData = { ...cellData, [id]: next };
+    }
+  }
+  const present = new Set(cellIds);
+  const removed = state.cellIds.filter((id) => !present.has(id));
+  if (removed.length > 0) {
+    const gone = new Set(removed);
+    const keep = <V>(record: Record<CellId, V>): Record<CellId, V> =>
+      Object.fromEntries(
+        Object.entries(record).filter(([id]) => !gone.has(id as CellId)),
+      ) as Record<CellId, V>;
+    cellData = keep(cellData);
+    cellRuntime = keep(cellRuntime);
+    cellHandles = keep(cellHandles);
+  }
+  if (
+    cellIds === state.cellIds &&
+    cellData === state.cellData &&
+    removed.length === 0
+  ) {
+    return state;
+  }
+  return { ...state, cellIds, cellData, cellRuntime, cellHandles };
+}
+
+/**
+ * Reconcile the model's document and name its columns, now and on each
+ * change, until the signal aborts.
+ *
+ * TODO(MO-8028): Delete with `applyDocument`.
+ */
+export function followDocument({
+  store,
+  model,
+  reconcile,
+  signal,
+}: {
+  store: ReturnType<typeof createStore>;
+  model: Pick<DocumentModel, "documentAtom">;
+  reconcile: (document: EditableDocument) => void;
+  signal: AbortSignal;
+}): void {
+  const follow = () => {
+    const document = store.get(model.documentAtom);
+    if (document !== null) {
+      reconcile(document);
+      store.set(followColumnsAtom, document);
+    }
+  };
+  const unsubscribe = store.sub(model.documentAtom, follow);
+  signal.addEventListener("abort", unsubscribe, { once: true });
+  follow();
+}
+
+// Editing the document ------------------------------------------------------
+
+/**
+ * The edit that writes the code a reducer action changed, or null when none
+ * did. Order, creation, deletion, names and configs are edited on the model
+ * directly by their atoms.
+ */
+function diffNotebook(
+  prev: NotebookState,
+  next: NotebookState,
+): DocumentEdit | null {
+  const steps: Array<(tx: DocumentEditor) => void> = [];
+  for (const id of next.cellIds) {
+    const cell = next.cellData[id];
+    const before = prev.cellData[id];
+    if (before !== undefined && cell !== before && before.code !== cell.code) {
+      steps.push((tx) => tx.setCode(id, cell.code));
+    }
+  }
+  if (steps.length === 0) {
+    return null;
+  }
+  return (tx) => {
+    for (const step of steps) {
+      step(tx);
+    }
+  };
+}
+
+/**
+ * Middleware for the notebook reducer. Writes what an action changed about
+ * the cells and their order into the document model as one edit.
+ *
+ * TODO(MO-8028): Only code is left in `diffNotebook`. The middleware goes
+ * with it, once the editors bind to the model.
+ */
+export function documentEditMiddleware(
+  prev: NotebookState,
+  next: NotebookState,
+  action: CellAction,
+): void {
+  // The document replaces the notebook's cells, so following it is no edit.
+  if (action.type === "reconcileDocument") {
+    return;
+  }
+  if (prev.cellIds === next.cellIds && prev.cellData === next.cellData) {
+    return;
+  }
+  const model = store.get(activeDocumentModelAtom);
+  if (model === null) {
+    return;
+  }
+  const edit = diffNotebook(prev, next);
+  if (edit !== null) {
+    store.set(model.editAtom, edit);
+  }
+}
+
+// Commands that read the document on the host -------------------------------
+
+/**
+ * Send this client's edits to the host before a command that reads them
+ * there. Without a document or a backend, as on a static page, there is
+ * nothing to send and the command proceeds.
+ */
+export async function flushDocument(): Promise<void> {
+  const model = store.get(activeDocumentModelAtom);
+  if (
+    model === null ||
+    store.get(model.syncStatusAtom).status === "unavailable"
+  ) {
+    return;
+  }
+  await model.flush();
+}
+
+/**
+ * Run a legacy save after this client's edits reach the host, and keep
+ * later edits local until it finishes. The save carries the whole
+ * notebook and the host takes it as the document, so an edit sent
+ * meanwhile would be overwritten. When the edits cannot be sent the save
+ * still runs, and the model resumes against the saved document.
+ *
+ * TODO(MO-8028): Goes with the legacy save, along with the hold.
+ */
+export async function withDocumentSave<T>(save: () => Promise<T>): Promise<T> {
+  const model = store.get(activeDocumentModelAtom);
+  if (model === null) {
+    return save();
+  }
+  let flushed = true;
+  try {
+    await model.flush();
+  } catch {
+    flushed = false;
+  }
+  const release = model.hold();
+  let result: T;
+  try {
+    result = await save();
+  } finally {
+    release();
+  }
+  if (!flushed) {
+    void model.retry().catch(() => undefined);
+  }
+  return result;
+}

package/src/core/cells/edit.ts

@@ -0,0 +1,30 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/** The active document model, as the notebook operations reach it. */
+
+import type { Getter, Setter } from "jotai";
+import type { DocumentModel, EditableDocument } from "@/core/notebook/document";
+import { activeDocumentModelAtom } from "../session/active-notebook";
+import { notebookAtom } from "./cells";
+import type { CellId } from "./ids";
+
+export function modelOf(get: Getter): DocumentModel {
+  const model = get(activeDocumentModelAtom);
+  if (!model) {
+    throw new Error("The notebook has no document to edit");
+  }
+  return model;
+}
+
+export function documentOf(get: Getter): EditableDocument {
+  const document = get(modelOf(get).documentAtom);
+  if (!document) {
+    throw new Error("The notebook has no document to edit");
+  }
+  return document;
+}
+
+/** Scroll to and focus the cell once it mounts. */
+export function focusWhenMounted(set: Setter, cellId: CellId): void {
+  set(notebookAtom, (state) => ({ ...state, scrollKey: cellId }));
+}

package/src/core/cells/editor.ts

@@ -0,0 +1,82 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/** What only this browser knows about cells: hidden code showing for now, and editor state to restore. */
+
+import { atom, useAtomValue } from "jotai";
+import { useMemo } from "react";
+import type { SerializedEditorState } from "../codemirror/types";
+import type { CellId } from "./ids";
+
+/**
+ * Hidden cells whose code is showing for now: a cell being edited, one just
+ * created, or one just made hidden. Blurring the cell hides it again.
+ */
+export const shownHiddenCodeAtom = atom<ReadonlySet<CellId>>(new Set<CellId>());
+
+export const useShowsHiddenCode = (cellId: CellId) =>
+  useAtomValue(
+    useMemo(
+      () => atom((get) => get(shownHiddenCodeAtom).has(cellId)),
+      [cellId],
+    ),
+  );
+
+/** Whether a cell's code is hidden on the page. */
+export function isCodeHidden(
+  hideCode: boolean | undefined,
+  shown: ReadonlySet<CellId>,
+  cellId: CellId,
+): boolean {
+  return Boolean(hideCode) && !shown.has(cellId);
+}
+
+export const showHiddenCodeAtom = atom(
+  null,
+  (_get, set, { cellId }: { cellId: CellId }): void => {
+    set(shownHiddenCodeAtom, (cells) => new Set([...cells, cellId]));
+  },
+);
+
+/** Hide a cell's code again. Returns whether it was showing. */
+export const hideShownCodeAtom = atom(
+  null,
+  (get, set, { cellId }: { cellId: CellId }): boolean => {
+    if (!get(shownHiddenCodeAtom).has(cellId)) {
+      return false;
+    }
+    set(shownHiddenCodeAtom, (cells) => {
+      const next = new Set(cells);
+      next.delete(cellId);
+      return next;
+    });
+    return true;
+  },
+);
+
+/**
+ * Editor state for cells about to mount again, such as a cell undo brings
+ * back. The editor takes its entry when it mounts, and deleting the cell
+ * drops it.
+ */
+export const restoredEditorStatesAtom = atom<
+  ReadonlyMap<CellId, SerializedEditorState>
+>(new Map<CellId, SerializedEditorState>());
+
+export const useRestoredEditorState = (cellId: CellId) =>
+  useAtomValue(
+    useMemo(
+      () => atom((get) => get(restoredEditorStatesAtom).get(cellId) ?? null),
+      [cellId],
+    ),
+  );
+
+export const takeRestoredEditorStateAtom = atom(
+  null,
+  (_get, set, { cellId }: { cellId: CellId }): void => {
+    set(restoredEditorStatesAtom, (states) => {
+      const next = new Map(states);
+      next.delete(cellId);
+      return next;
+    });
+  },
+);

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

@@ -0,0 +1,63 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { describeError } from "@/core/errors/error-entries";
+import type { MarimoError } from "@/core/kernel/messages";
+import { sanitizeHtml } from "@/plugins/core/sanitize-html";
+import { parseHtmlContent } from "@/utils/dom";
+import type { CellId } from "./ids";
+
+export interface CellOutputMessage<Output> {
+  type: "cell-output";
+  cell_id: CellId;
+  code?: string;
+  output: Output;
+}
+
+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; tracebackFormat: "html" | "text" }
+  ),
+): CellOutputMessage<ErrorMessageOutput> {
+  let message: string;
+  let traceback: string;
+  if ("errors" in evidence) {
+    message = evidence.errors.map(describeError).join("\n");
+    traceback = evidence.errors
+      .flatMap((error) =>
+        "traceback" in error && error.traceback
+          ? [parseHtmlContent(sanitizeHtml(error.traceback))]
+          : [],
+      )
+      .join("\n\n");
+  } else {
+    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,
+    output: {
+      type: "error",
+      instructions: ERROR_MESSAGE_INSTRUCTIONS,
+      message,
+      ...(traceback ? { traceback } : {}),
+    },
+    ...(evidence.code === undefined ? {} : { code: evidence.code }),
+  };
+}