@marimo-team/islands 0.25.3-dev273 → 0.25.3-dev279

package/src/core/executions/freshness.ts

@@ -0,0 +1,164 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/**
+ * Whether each cell's result still reflects the document and the values
+ * it read, by the host protocol's rules.
+ *
+ * A completed execution is current when its code fingerprint equals the
+ * cell's, every variable it depends on still holds the recorded revision,
+ * every name it depends on that was unbound is still unbound, and the
+ * executions that bound those variables are current. See the freshness
+ * section of `protocols/host/spec.md`.
+ *
+ * The protocol also ranks why a result is outdated. The editor asks two
+ * questions of its own, so that is what this reports; the ranked reason
+ * can come back with a reader. Two editor concerns are folded in: a name
+ * bound only by an earlier runtime is unbound in this one, and a queued or
+ * running execution for the cell's current source already covers it.
+ */
+
+import type * as Protocol from "@marimo-team/client/protocol";
+import type { Executions, Results } from "@/core/notebook/replica";
+
+export interface CellFreshness {
+  /** This cell's source changed since its result. */
+  readonly sourceChanged: boolean;
+  /**
+   * A value the result read changed since, by a rerun or an update, here
+   * or upstream. An ancestor that was only edited does not count: its
+   * values are still the ones this result read.
+   */
+  readonly inputsChanged: boolean;
+}
+
+/** Current, and also a cell with no completed execution to compare. */
+const CURRENT: CellFreshness = { sourceChanged: false, inputsChanged: false };
+
+/** What freshness is derived from. */
+export interface CellFreshnessInputs {
+  /** The document's cells, for the fingerprint of each cell's source. */
+  readonly cells: ReadonlyMap<Protocol.CellId, Protocol.Cell>;
+  /** The stream's executions, for the variables currently bound. */
+  readonly executions: Executions;
+  /** Each cell's last completed record, the result being compared. */
+  readonly results: Results;
+}
+
+/** Freshness by cell id, as `freshnessOf` builds it. */
+export type CellFreshnessLookup = (id: Protocol.CellId) => CellFreshness;
+
+/** The variables bound in the namespace right now, by name. */
+function boundVariables(
+  executions: Executions,
+): ReadonlyMap<string, Protocol.Variable[]> {
+  const byName = new Map<string, Protocol.Variable[]>();
+  for (const execution of executions.executions.values()) {
+    for (const variable of execution.variables.values()) {
+      const bound = byName.get(variable.name);
+      if (bound === undefined) {
+        byName.set(variable.name, [variable]);
+      } else {
+        bound.push(variable);
+      }
+    }
+  }
+  return byName;
+}
+
+/**
+ * Compares results against the document and the namespace.
+ *
+ * Build one per set of inputs and ask it about each cell, since the
+ * bound variables are indexed once and a binding execution's freshness is
+ * computed once however many results depend on it.
+ */
+export function freshnessOf(inputs: CellFreshnessInputs): CellFreshnessLookup {
+  const bound = boundVariables(inputs.executions);
+  const memo = new Map<Protocol.ExecutionId, CellFreshness>();
+  const recordOf = (id: Protocol.ExecutionId) =>
+    inputs.executions.executions.get(id)?.record;
+
+  /** Whether a value the record read has changed, or one upstream has. */
+  function inputsChanged(
+    record: Protocol.Execution,
+    visiting: ReadonlySet<Protocol.ExecutionId>,
+  ): boolean {
+    const path = new Set(visiting).add(record.id);
+    for (const [name, revision] of Object.entries(record.depends_on)) {
+      const variables = bound.get(name) ?? [];
+      if (revision === null) {
+        // A result retained from an earlier runtime binds nothing here.
+        if (
+          variables.some(
+            (v) => recordOf(v.execution_id)?.runtime_id === record.runtime_id,
+          )
+        ) {
+          return true;
+        }
+        continue;
+      }
+      const variable = variables.find(
+        (candidate) => candidate.revision.execution === revision.execution,
+      );
+      if (
+        variable === undefined ||
+        variable.revision.update !== revision.update
+      ) {
+        return true;
+      }
+      const binder = recordOf(variable.execution_id);
+      if (binder === undefined) {
+        return true;
+      }
+      if (!path.has(binder.id) && ofRecord(binder, path).inputsChanged) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /** Whether a newer execution of the cell already runs its current source. */
+  function coveredByPending(
+    cell: Protocol.Cell,
+    record: Protocol.Execution,
+  ): boolean {
+    const latest = inputs.executions.latest.get(cell.id);
+    if (latest === undefined || latest === record.id) {
+      return false;
+    }
+    const pending = recordOf(latest);
+    return (
+      pending !== undefined &&
+      pending.status !== "completed" &&
+      pending.code_fingerprint === cell.code_fingerprint
+    );
+  }
+
+  function ofRecord(
+    record: Protocol.Execution,
+    visiting: ReadonlySet<Protocol.ExecutionId>,
+  ): CellFreshness {
+    const known = memo.get(record.id);
+    if (known !== undefined) {
+      return known;
+    }
+    const cell =
+      record.cell_id === null ? undefined : inputs.cells.get(record.cell_id);
+    const freshness: CellFreshness = {
+      sourceChanged:
+        cell === undefined ||
+        (cell.code_fingerprint !== record.code_fingerprint &&
+          !coveredByPending(cell, record)),
+      inputsChanged: inputsChanged(record, visiting),
+    };
+    memo.set(record.id, freshness);
+    return freshness;
+  }
+
+  return (id) => {
+    const result = inputs.results.get(id);
+    return result === null || result === undefined
+      ? CURRENT
+      : ofRecord(result, new Set());
+  };
+}

package/src/core/executions/hooks.ts

@@ -5,7 +5,8 @@ import { dequal } from "dequal";
 import { useAtomValue } from "jotai";
 import { selectAtom } from "jotai/utils";
 import { useMemo } from "react";
-import { cellExecutionInputsAtom } from "./atoms";
+import { cellExecutionInputsAtom, cellFreshnessAtom } from "./atoms";
+import type { CellFreshness } from "./freshness";
 import { type CellExecutionView, cellExecutionView } from "./select";
 
 /**
@@ -29,3 +30,18 @@ export function useCellExecution(id: Protocol.CellId): CellExecutionView {
   );
   return useAtomValue(cellAtom);
 }
+
+/**
+ * Whether a cell's result is current, by the host protocol's rules over
+ * the confirmed document and the executions mirror.
+ *
+ * The confirmed document is what the host has accepted, so an edit reads
+ * as such once the model has flushed it, not on the keystroke.
+ */
+export function useCellFreshness(id: Protocol.CellId): CellFreshness {
+  const cellAtom = useMemo(
+    () => selectAtom(cellFreshnessAtom, (freshness) => freshness(id), dequal),
+    [id],
+  );
+  return useAtomValue(cellAtom);
+}

package/src/core/executions/index.ts

@@ -10,6 +10,7 @@
 
 export {
   cellExecutionInputsAtom,
+  cellFreshnessAtom,
   notebookIsRunningAtom,
   notebookQueuedOrRunningCountAtom,
   observeCellMessage,
@@ -18,7 +19,8 @@ export {
   waitForRuntimeRunning,
   withdrawCells,
 } from "./atoms";
-export { useCellExecution } from "./hooks";
+export type { CellFreshness, CellFreshnessLookup } from "./freshness";
+export { useCellExecution, useCellFreshness } from "./hooks";
 export {
   type CellExecutionInputs,
   type CellExecutionView,

package/src/core/islands/bootstrap.ts

@@ -221,7 +221,6 @@ function handleNotification(
         handleKernelReady(msg, {
           autoInstantiate: true,
           cells: notebookCells(store.get(notebookAtom)),
-          setLastRun: actions.setLastRun,
           resetCellRuntimes: actions.resetCellRuntimes,
           setLayoutData: Functions.NOOP,
           setCapabilities: Functions.NOOP,

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

@@ -9,6 +9,7 @@ import {
   describe,
   expect,
   it,
+  vi,
 } from "vitest";
 import { cellId } from "@/__tests__/branded";
 import { MockNotebook } from "@/__mocks__/notebook";
@@ -22,6 +23,7 @@ import {
 import { islandsPendingInitialRunsAtom } from "@/core/islands/state";
 import { requestClientAtom } from "@/core/network/requests";
 import { store } from "@/core/state/jotai";
+import { buildIslandHTML } from "../../__tests__/test-utils";
 import { parseMarimoIslandApps } from "../../parse";
 import { MarimoIslandElement } from "../web-components";
 
@@ -45,9 +47,55 @@ beforeEach(() => {
 afterEach(async () => {
   await actAndFlush(() => document.body.replaceChildren());
   store.set(requestClientAtom, null);
+  document.body.removeAttribute("style");
+  vi.unstubAllEnvs();
 });
 
 describe("MarimoIslandElement lifecycle", () => {
+  it.each([true, false])(
+    "synchronizes the theme of a reactive=%s island across reconnects",
+    async (reactive) => {
+      vi.stubEnv("VITE_MARIMO_ISLANDS", "true");
+      if (reactive) {
+        setNotebook("runtime-cell", "runtime output");
+      }
+      const { container, island } = createThemeIsland(reactive);
+      document.body.style.colorScheme = "dark";
+      await actAndFlush(() => document.body.append(container));
+      expect(island).toHaveClass("marimo", "dark");
+      await actAndFlush(() => {
+        document.body.style.colorScheme = "light";
+      });
+      expect(island).toHaveClass("marimo", "light");
+      expect(island).not.toHaveClass("dark");
+      await actAndFlush(() => island.remove());
+      await actAndFlush(() => {
+        document.body.style.colorScheme = "dark";
+      });
+      expect(island).toHaveClass("light");
+      await actAndFlush(() => container.append(island));
+      expect(island).toHaveClass("dark");
+    },
+  );
+
+  it("can disconnect before its scheduled render and reconnect with the current theme", async () => {
+    vi.stubEnv("VITE_MARIMO_ISLANDS", "true");
+    const { container, island } = createThemeIsland(false);
+    document.body.style.colorScheme = "dark";
+    await actAndFlush(() => {
+      document.body.append(container);
+      island.remove();
+    });
+    expect(island.querySelector("marimo-cell-output")).not.toBeNull();
+    await actAndFlush(() => {
+      document.body.style.colorScheme = "light";
+    });
+    expect(island).toHaveClass("dark");
+    await actAndFlush(() => container.append(island));
+    expect(island).toHaveClass("light");
+    expect(island.textContent).toContain("static output");
+  });
+
   it("keeps static output until the initial run completes", async () => {
     store.set(islandsPendingInitialRunsAtom, new Set([1]));
     setNotebook("runtime-cell", "runtime output");
@@ -182,6 +230,21 @@ describe("MarimoIslandElement lifecycle", () => {
   });
 });
 
+function createThemeIsland(reactive: boolean) {
+  const container = document.createElement("div");
+  container.innerHTML = buildIslandHTML([
+    {
+      appId: "app-1",
+      cellId: "runtime-cell",
+      reactive,
+      code: "x = 1",
+      output: "<pre>static output</pre>",
+    },
+  ]);
+  const island = container.querySelector<HTMLElement>(ISLAND_TAG_NAMES.ISLAND)!;
+  return { container, island };
+}
+
 function setNotebook(id: string, output?: string): void {
   const runtimeCellId = cellId(id);
   store.set(

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

@@ -10,6 +10,7 @@ import { OBJECT_ID_ATTR } from "@/core/dom/ui-element-constants";
 import { UI_ELEMENT_REGISTRY } from "@/core/dom/uiregistry";
 import { LocaleProvider } from "@/core/i18n/locale-provider";
 import { renderHTML } from "@/plugins/core/RenderHTML";
+import { resolvedThemeAtom } from "@/theme/useTheme";
 import { invariant } from "@/utils/invariant";
 import type { CellId, UIElementId } from "../../cells/ids";
 import { store } from "../../state/jotai";
@@ -44,6 +45,7 @@ export class MarimoIslandElement extends HTMLElement {
   private runtimeAppId?: string;
   private runtimeCellId?: CellId;
   private unsubscribeCellIds?: () => void;
+  private unsubscribeTheme?: () => void;
 
   public static readonly tagName = ISLAND_TAG_NAMES.ISLAND;
   public static readonly outputTagName = ISLAND_TAG_NAMES.CELL_OUTPUT;
@@ -132,6 +134,13 @@ export class MarimoIslandElement extends HTMLElement {
       ? this.cellId
       : undefined;
     this.syncCellIdsSubscription();
+    const syncTheme = () => {
+      const theme = store.get(resolvedThemeAtom);
+      this.classList.toggle("dark", theme === "dark");
+      this.classList.toggle("light", theme === "light");
+    };
+    this.unsubscribeTheme = store.sub(resolvedThemeAtom, syncTheme);
+    syncTheme();
     queueMicrotask(() => {
       // Guard against disconnect between connectedCallback and microtask
       if (
@@ -297,6 +306,8 @@ export class MarimoIslandElement extends HTMLElement {
    * Cleanup when element is removed from DOM
    */
   public disconnectedCallback(): void {
+    this.unsubscribeTheme?.();
+    this.unsubscribeTheme = undefined;
     this.removeEventListener(
       ISLAND_SOURCE_CHANGED_EVENT,
       this.handleSourceChanged,

package/src/core/kernel/handlers.ts

@@ -60,7 +60,6 @@ export function handleKernelReady(
     autoInstantiate: boolean;
     /** The notebook's cells, as the host document provided them. */
     cells: CellData[];
-    setLastRun: ReducerCellActions["setLastRun"];
     resetCellRuntimes: ReducerCellActions["resetCellRuntimes"];
     setLayoutData: (payload: {
       layoutView: LayoutType;
@@ -73,7 +72,6 @@ export function handleKernelReady(
   const {
     autoInstantiate,
     cells,
-    setLastRun,
     resetCellRuntimes,
     setLayoutData,
     setCapabilities,
@@ -82,8 +80,6 @@ export function handleKernelReady(
   const { resumed, ui_values, capabilities, auto_instantiated } = data;
 
   resetCellRuntimes();
-  // TODO(MO-8403): Delete with `lastCodeRun`.
-  setLastRun({ lastCodeRun: data.last_executed_code ?? {} });
   const layoutState = buildLayoutState(data, cells, setLayoutData);
 
   setCapabilities(capabilities);

package/src/core/session/useNotebookSession.tsx

@@ -92,12 +92,8 @@ export function useNotebookSession(opts: {
   const { showBoundary } = useErrorBoundary();
   const store = useStore();
 
-  const {
-    handleCellMessage,
-    reconcileDocument,
-    setLastRun,
-    resetCellRuntimes,
-  } = useReducerActions();
+  const { handleCellMessage, reconcileDocument, resetCellRuntimes } =
+    useReducerActions();
   const { reconcileStagedCells } = useStagedAICellsActions();
   const { addCellNotification } = useRunsActions();
   const setInitialRunCompleted = useSetAtom(initialRunCompletedAtom);
@@ -154,7 +150,6 @@ export function useNotebookSession(opts: {
         const layout = handleKernelReady(msg.data, {
           autoInstantiate,
           cells: notebookCells(store.get(notebookAtom)),
-          setLastRun,
           resetCellRuntimes,
           setLayoutData,
           setCapabilities,

package/src/css/globals.css

@@ -128,14 +128,18 @@
     --cm-search-match-selected-background-dark: #6199ff88;
   }
 
+  .marimo.light {
+    color-scheme: light;
+  }
+
   :root:has(body.dark),
   .dark,
-  .marimo:is(.dark *) {
+  .marimo:not(.light):is(.dark *) {
     color-scheme: dark;
   }
 
   .dark,
-  .marimo:is(.dark *) {
+  .marimo:not(.light):is(.dark *) {
     --ring: var(--blue-8, #2870bd);
     --destructive: var(--red-6, #72232d);
     --destructive-hover: var(--red-7, #8c333a);

package/src/plugins/impl/DataEditorPlugin.tsx

@@ -92,13 +92,9 @@ interface Props {
 const LoadingDataEditor = (props: Props) => {
   const [editorState, setEditorState] = useState<EditorState | null>(null);
 
-  // Load the data
   const { data: loadedState, error } = useAsyncData(async () => {
     const withoutExternalTypes = toFieldTypes(props.fieldTypes ?? []);
 
-    // If we already have the data, return it
-    // Otherwise, load the data from the URL. Vega's CSV parser takes a
-    // plain `Record`; column order doesn't matter for parsing.
     const localData = Array.isArray(props.data)
       ? props.data
       : await vegaLoadData<EditorRow>(

package/src/plugins/impl/data-editor/__tests__/column-types.test.ts

@@ -10,6 +10,11 @@ describe("normalizeConfiguredColumns", () => {
     vi.restoreAllMocks();
   });
 
+  it("preserves the data reference when no columns are configured", () => {
+    const data = [{ label: "01", done: "yes" }];
+    expect(normalizeConfiguredColumns(data, new Map())).toBe(data);
+  });
+
   it("normalizes large integer boolean values from the CSV loader", async () => {
     vi.spyOn(vegaLoader, "load").mockResolvedValueOnce(
       "done,label\n9007199254740992,01\n-9007199254740992,02\n0,03\n",

package/src/plugins/impl/data-editor/__tests__/glide-data-editor.test.tsx

@@ -65,7 +65,11 @@ vi.mock("@glideapps/glide-data-grid", async () => {
 });
 
 vi.mock("@glideapps/glide-data-grid-cells", () => ({
-  DropdownCell: { kind: "dropdown-renderer" },
+  DropdownCell: {
+    kind: "dropdown-renderer",
+    isMatch: (cell: { data: { kind: string } }) =>
+      cell.data.kind === "dropdown-cell",
+  },
 }));
 
 vi.mock("@/theme/useTheme", () => ({
@@ -74,11 +78,11 @@ vi.mock("@/theme/useTheme", () => ({
 
 const editorProps = {
   data: [{ name: "alice" }],
-  columnFields: new Map([["name", "string"]]) as Map<string, "string">,
-  editableColumns: "all" as const,
+  columnFields: new Map([["name", "string"]]),
+  editableColumns: "all",
   columnTypes: new Map(),
   onAddEdits: vi.fn(),
-};
+} satisfies React.ComponentProps<typeof GlideDataEditor>;
 
 describe("GlideDataEditor portal", () => {
   let fullscreenElement: Element | null;
@@ -148,7 +152,7 @@ describe("GlideDataEditor portal", () => {
       },
     });
     expect(capturedDataEditor.customRenderers).toEqual([
-      { kind: "dropdown-renderer" },
+      { kind: "dropdown-renderer", isMatch: expect.any(Function) },
     ]);
   });
 

package/src/plugins/impl/data-editor/column-types.ts

@@ -33,6 +33,9 @@ export function normalizeConfiguredColumns(
   data: EditorRow[],
   columnTypes: ColumnTypes,
 ): EditorRow[] {
+  if (columnTypes.size === 0) {
+    return data;
+  }
   return data.map((row) => {
     const normalizedRow = { ...row };
     for (const [columnName, columnType] of columnTypes) {

package/src/plugins/impl/data-editor/glide-data-editor.tsx

@@ -55,11 +55,13 @@ import {
 } from "./types";
 
 function getEditedValue(newValue: EditableGridCell): unknown {
-  if (newValue.kind !== GridCellKind.Custom) {
-    return newValue.data;
+  if (
+    newValue.kind === GridCellKind.Custom &&
+    DropdownCellRenderer.isMatch(newValue)
+  ) {
+    return newValue.data.value;
   }
-  const data = newValue.data as { kind?: unknown; value?: unknown };
-  return data.kind === "dropdown-cell" ? data.value : newValue.data;
+  return newValue.data;
 }
 
 interface GlideDataEditorProps {
@@ -190,7 +192,6 @@ export const GlideDataEditor = ({
       const key = column.title;
 
       // Deletes are not handled by validateCell, so we need to handle them here.
-      // Custom dropdown cells carry their selected value inside their data.
       let newData = getEditedValue(newValue);
       if (Array.isArray(column.configuredType)) {
         if (

package/src/plugins/impl/data-editor/glide-utils.ts

@@ -132,7 +132,6 @@ export function pasteCells(options: {
   const { range } = selection.current;
   const { x: startCol, y: startRow } = range;
 
-  // Read clipboard data
   navigator.clipboard
     .readText()
     .then((clipboardText) => {
@@ -140,43 +139,25 @@ export function pasteCells(options: {
         return;
       }
 
-      // Parse tab-separated values
-      const rows = clipboardText.split("\n").filter((row) => row.trim());
-      const parsedData: string[][] = [];
-
-      for (const row of rows) {
-        const cells = row.split("\t");
-        parsedData.push(cells);
-      }
-
-      if (parsedData.length === 0) {
-        return;
-      }
+      const parsedData = clipboardText
+        .split("\n")
+        .filter((row) => row.trim())
+        .map((row) => row.split("\t"));
 
       const edits: Edits["edits"] = [];
       const editableColumnSet =
         editableColumns === "all" ? null : new Set(editableColumns);
 
       for (const [rowIndex, dataRow] of parsedData.entries()) {
-        if (!dataRow) {
-          continue;
-        }
-
         const targetRowIdx = startRow + rowIndex;
 
-        // Check if we've exceeded the data bounds
         if (targetRowIdx >= data.length) {
           break;
         }
 
         for (const [colIndex, cellValue] of dataRow.entries()) {
-          if (cellValue === undefined) {
-            continue;
-          }
-
           const targetColIdx = startCol + colIndex;
 
-          // Check if we've exceeded the column bounds
           if (targetColIdx >= columns.length) {
             break;
           }
@@ -191,13 +172,13 @@ export function pasteCells(options: {
             continue;
           }
 
-          // Convert the value based on the cell type
           let convertedValue: unknown = cellValue;
 
-          if (Array.isArray(columnType)) {
-            if (!isValidCellValue(dataType, cellValue, columnType)) {
-              continue;
-            }
+          if (
+            Array.isArray(columnType) &&
+            !isValidCellValue(dataType, cellValue, columnType)
+          ) {
+            continue;
           }
 
           switch (dataType) {
@@ -243,12 +224,9 @@ export function pasteCells(options: {
               continue;
           }
 
-          // Get the column ID from the columns array using the title
-          const columnId = columns[targetColIdx].title;
-
           edits.push({
             rowIdx: targetRowIdx,
-            columnId,
+            columnId: column.title,
             value: convertedValue,
           });
         }

package/src/plugins/impl/data-editor/types.ts

@@ -6,8 +6,6 @@ import type { DataType } from "@/core/kernel/messages";
 
 export type EditorRow = Record<string, unknown>;
 
-// Shared transport for specialized column editors: dropdown columns use a
-// string array, while checkbox columns use the boolean discriminator.
 export type ColumnType = "boolean" | string[];
 export type ColumnTypes = Map<string, ColumnType>;