A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
fix(messaging): stop reusable hint flicker on cell updates (#9782)
Kiran Gadhavee76394043b7c
diff --git a/frontend/src/core/cells/__tests__/__snapshots__/cells.test.ts.snap b/frontend/src/core/cells/__tests__/__snapshots__/cells.test.ts.snapindex 000754c558..2e84b32c6e 100644--- a/frontend/src/core/cells/__tests__/__snapshots__/cells.test.ts.snap+++ b/frontend/src/core/cells/__tests__/__snapshots__/cells.test.ts.snap@@ -80,7 +80,6 @@ exports[`cell reducer > can initialize stdin 3`] = `"output": null,"runElapsedTimeMs": null,"runStartTimestamp": null,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "queued",@@ -110,7 +109,6 @@ exports[`cell reducer > can initialize stdin 4`] = `"output": null,"runElapsedTimeMs": null,"runStartTimestamp": 20,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "running",@@ -147,7 +145,6 @@ exports[`cell reducer > can initialize stdin 5`] = `"output": null,"runElapsedTimeMs": null,"runStartTimestamp": 20,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "running",@@ -184,7 +181,6 @@ exports[`cell reducer > can initialize stdin 6`] = `"output": null,"runElapsedTimeMs": null,"runStartTimestamp": 20,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "running",@@ -227,7 +223,6 @@ exports[`cell reducer > can initialize stdin 7`] = `"output": null,"runElapsedTimeMs": null,"runStartTimestamp": 20,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "running",@@ -271,7 +266,6 @@ exports[`cell reducer > can initialize stdin 8`] = `"output": null,"runElapsedTimeMs": null,"runStartTimestamp": 20,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "running",@@ -321,7 +315,6 @@ exports[`cell reducer > can initialize stdin 9`] = `"output": null,"runElapsedTimeMs": null,"runStartTimestamp": 20,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "running",@@ -387,7 +380,6 @@ exports[`cell reducer > can receive console when the cell is idle and will clear"output": null,"runElapsedTimeMs": null,"runStartTimestamp": null,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "queued",@@ -424,7 +416,6 @@ exports[`cell reducer > can receive console when the cell is idle and will clear"output": null,"runElapsedTimeMs": null,"runStartTimestamp": null,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "queued",@@ -454,7 +445,6 @@ exports[`cell reducer > can receive console when the cell is idle and will clear"output": null,"runElapsedTimeMs": null,"runStartTimestamp": 20,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "running",@@ -491,7 +481,6 @@ exports[`cell reducer > can receive console when the cell is idle and will clear"output": null,"runElapsedTimeMs": 2000,"runStartTimestamp": null,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "idle",@@ -521,7 +510,6 @@ exports[`cell reducer > can run a stale cell 1`] = `"output": null,"runElapsedTimeMs": null,"runStartTimestamp": null,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "queued",@@ -551,7 +539,6 @@ exports[`cell reducer > can run a stale cell 2`] = `"output": null,"runElapsedTimeMs": null,"runStartTimestamp": null,- "serialization": undefined,"serializedEditorState": null,"staleInputs": true,"status": "queued",@@ -581,7 +568,6 @@ exports[`cell reducer > can run a stopped cell 1`] = `"output": null,"runElapsedTimeMs": null,"runStartTimestamp": null,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "queued",@@ -611,7 +597,6 @@ exports[`cell reducer > can run a stopped cell 2`] = `"output": null,"runElapsedTimeMs": null,"runStartTimestamp": null,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "idle",@@ -652,7 +637,6 @@ exports[`cell reducer > can run a stopped cell 3`] = `},"runElapsedTimeMs": null,"runStartTimestamp": null,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "idle",@@ -693,7 +677,6 @@ exports[`cell reducer > can run a stopped cell 4`] = `},"runElapsedTimeMs": null,"runStartTimestamp": null,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "queued",@@ -723,7 +706,6 @@ exports[`cell reducer > can run a stopped cell 5`] = `"output": null,"runElapsedTimeMs": null,"runStartTimestamp": 40,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "running",@@ -840,7 +822,6 @@ exports[`cell reducer > can run cell and receive cell messages 4`] = `"output": null,"runElapsedTimeMs": null,"runStartTimestamp": null,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "queued",@@ -870,7 +851,6 @@ exports[`cell reducer > can run cell and receive cell messages 5`] = `"output": null,"runElapsedTimeMs": null,"runStartTimestamp": 20,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "running",@@ -907,7 +887,6 @@ exports[`cell reducer > can run cell and receive cell messages 6`] = `"output": null,"runElapsedTimeMs": null,"runStartTimestamp": 20,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "running",@@ -949,7 +928,6 @@ exports[`cell reducer > can run cell and receive cell messages 7`] = `},"runElapsedTimeMs": 13000,"runStartTimestamp": null,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "idle",@@ -992,7 +970,6 @@ import numpy",},"runElapsedTimeMs": 13000,"runStartTimestamp": null,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "idle",@@ -1034,7 +1011,6 @@ exports[`cell reducer > can run cell and receive cell messages 9`] = `},"runElapsedTimeMs": 13000,"runStartTimestamp": null,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "idle",@@ -1077,7 +1053,6 @@ import numpy",},"runElapsedTimeMs": 13000,"runStartTimestamp": null,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "idle",@@ -1127,7 +1102,6 @@ import numpy",},"runElapsedTimeMs": 11000,"runStartTimestamp": null,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "idle",@@ -1175,7 +1149,6 @@ import numpy",},"runElapsedTimeMs": 11000,"runStartTimestamp": null,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "idle",@@ -1303,7 +1276,6 @@ exports[`cell reducer > errors reset status to idle 4`] = `},"runElapsedTimeMs": null,"runStartTimestamp": null,- "serialization": undefined,"serializedEditorState": null,"staleInputs": false,"status": "idle",diff --git a/frontend/src/core/cells/__tests__/cell.test.ts b/frontend/src/core/cells/__tests__/cell.test.tsindex ccd8aa45d3..70c3f2958c 100644--- a/frontend/src/core/cells/__tests__/cell.test.ts+++ b/frontend/src/core/cells/__tests__/cell.test.ts@@ -1,9 +1,10 @@/* Copyright 2026 Marimo. All rights reserved. */import { describe, expect, it } from "vitest";-import type { OutputMessage } from "@/core/kernel/messages";+import type { CellMessage, OutputMessage } from "@/core/kernel/messages";import type { RuntimeState } from "@/core/network/types";import type { Seconds } from "@/utils/time";-import { outputIsLoading, outputIsStale } from "../cell";+import { outputIsLoading, outputIsStale, transitionCell } from "../cell";+import { createCellRuntimeState } from "../types";const STATUSES: RuntimeState[] = ["queued",@@ -191,3 +192,29 @@ describe("outputIsStale", () => {expect(outputIsStale(cell, edited)).toBe(false);});});++describe("transitionCell serialization", () => {+ function cellMessage(serialization?: string | null): CellMessage {+ return {+ cell_id: "cell-1",+ ...(serialization === undefined ? {} : { serialization }),+ } as CellMessage;+ }++ it("leaves the hint unchanged when serialization is omitted", () => {+ const cell = createCellRuntimeState({ serialization: "Valid" });+ expect(transitionCell(cell, cellMessage()).serialization).toBe("Valid");+ });++ it("clears the hint when serialization is null", () => {+ const cell = createCellRuntimeState({ serialization: "Valid" });+ expect(transitionCell(cell, cellMessage(null)).serialization).toBeNull();+ });++ it("sets the hint when serialization is a string", () => {+ const cell = createCellRuntimeState();+ expect(transitionCell(cell, cellMessage("Valid")).serialization).toBe(+ "Valid",+ );+ });+});diff --git a/frontend/src/core/cells/cell.ts b/frontend/src/core/cells/cell.tsindex 082ca0d6f9..083e0f3fe9 100644--- a/frontend/src/core/cells/cell.ts+++ b/frontend/src/core/cells/cell.ts@@ -73,7 +73,11 @@ export function transitionCell(nextCell.output = message.output ?? nextCell.output;nextCell.staleInputs = message.stale_inputs ?? nextCell.staleInputs;nextCell.status = message.status ?? nextCell.status;- nextCell.serialization = message.serialization;+ // Tri-state partial update: an omitted field (undefined) leaves the hint+ // unchanged; null explicitly clears it; a string sets it.+ if (message.serialization !== undefined) {+ nextCell.serialization = message.serialization;+ }let didInterruptFromThisMessage = false;diff --git a/marimo/_messaging/notification.py b/marimo/_messaging/notification.pyindex 8dc845fbfe..0c80287b09 100644--- a/marimo/_messaging/notification.py+++ b/marimo/_messaging/notification.py@@ -61,8 +61,10 @@ class Notification(msgspec.Struct, tag_field="op"):class CellNotification(Notification, tag="cell-op"):"""Updates a cell's state in the frontend.- Only fields that are set (not None) will update the cell state.- Omitting a field leaves that aspect unchanged.+ This is a partial update: each field carries its own "unchanged" semantics,+ documented per field below. Most fields treat None as "unchanged"; fields+ that need to distinguish "unchanged" from "clear" use msgspec.UNSET for the+ former and None for the latter.Attributes:cell_id: Unique identifier of the cell being updated.@@ -71,7 +73,7 @@ class CellNotification(Notification, tag="cell-op"):status: Execution status (idle/running/stale/queued/disabled-transitively).stale_inputs: Whether cell has stale inputs from changed dependencies.run_id: Execution run ID for tracing. Auto-set from context.- serialization: Serialization status (TopLevelHints).+ serialization: Top-level reusability hint. UNSET unchanged, None clears, str sets.timestamp: Creation timestamp, auto-set."""@@ -82,7 +84,10 @@ class CellNotification(Notification, tag="cell-op"):status: RuntimeStateType | None = Nonestale_inputs: bool | None = Nonerun_id: RunId_t | None = None- serialization: str | None = None+ # Tri-state partial update: UNSET (omitted on the wire) leaves the cell's+ # serialization hint unchanged; None explicitly clears it (cell is no+ # longer a top-level definition); a string sets it.+ serialization: str | None | msgspec.UnsetType = msgspec.UNSETtimestamp: float = msgspec.field(default_factory=lambda: time.time())def __post_init__(self) -> None:diff --git a/marimo/_messaging/notification_utils.py b/marimo/_messaging/notification_utils.pyindex 1253e4a004..f97dbfdd46 100644--- a/marimo/_messaging/notification_utils.py+++ b/marimo/_messaging/notification_utils.py@@ -296,3 +296,22 @@ class CellNotificationUtils:CellNotification(cell_id=cell_id, serialization=str(status)),stream,)++ @staticmethod+ def broadcast_serialization_cleared(+ cell_id: CellId_t,+ stream: Stream | None = None,+ ) -> None:+ """Clear a cell's reusability hint (it is no longer a top-level def).++ Sends an explicit None: in the partial-update cell-op contract a+ missing field means "unchanged", so a concrete None is required to+ remove a previously shown hint.+ """+ # Import here to avoid circular dependency+ from marimo._messaging.notification import CellNotification++ broadcast_notification(+ CellNotification(cell_id=cell_id, serialization=None),+ stream,+ )diff --git a/marimo/_runtime/dataflow/graph.py b/marimo/_runtime/dataflow/graph.pyindex 8a0d558b36..bed6ae3e17 100644--- a/marimo/_runtime/dataflow/graph.py+++ b/marimo/_runtime/dataflow/graph.py@@ -47,6 +47,15 @@ class DirectedGraph(GraphTopology):)cycle_tracker: CycleTracker = field(default_factory=CycleTracker)+ # Cell ids whose last post-execution broadcast advertised a top-level+ # reusability hint. Tracked here (not on the per-run CellImpl, which is+ # replaced when a cell's code changes) so the hint can be cleared exactly+ # on the top-level -> non-top-level transition. Not topology; broadcast+ # bookkeeping that needs to survive cell re-registration.+ cells_serving_serialization_hint: set[CellId_t] = field(+ default_factory=set+ )+# This lock must be acquired during methods that mutate the graph; it's# only needed because a graph is shared between the kernel and the code# completion service. It should almost always be uncontended.diff --git a/marimo/_runtime/runner/hooks_post_execution.py b/marimo/_runtime/runner/hooks_post_execution.pyindex 6efefc29de..674c78807b 100644--- a/marimo/_runtime/runner/hooks_post_execution.py+++ b/marimo/_runtime/runner/hooks_post_execution.py@@ -453,6 +453,7 @@ def render_toplevel_defs() -> None:del run_resultvariable = cell.toplevel_variable+ served = ctx.graph.cells_serving_serialization_hintif variable is not None:extractor = TopLevelExtraction.from_graph(ctx.graph, cell=cell)serialization = list(iter(extractor))[-1]@@ -460,6 +461,15 @@ def render_toplevel_defs(serialization=serialization,cell_id=cell.cell_id,)+ served.add(cell.cell_id)+ elif cell.cell_id in served:+ # Cell stopped being a top-level definition: clear the prior hint.+ # Only broadcast on this transition so ordinary cells don't emit an+ # extra cell-op on every run.+ CellNotificationUtils.broadcast_serialization_cleared(+ cell_id=cell.cell_id,+ )+ served.discard(cell.cell_id)@kernel_tracer.start_as_current_span("run_pytest")diff --git a/marimo/_session/state/session_view.py b/marimo/_session/state/session_view.pyindex 20ad8f9b47..0758035cc1 100644--- a/marimo/_session/state/session_view.py+++ b/marimo/_session/state/session_view.py@@ -5,6 +5,8 @@ import timefrom dataclasses import dataclassfrom typing import Any, Literal, cast+import msgspec+from marimo import _loggersfrom marimo._data.models import DataSourceConnection, DataTablefrom marimo._messaging.cell_output import CellChannel, CellOutput@@ -657,4 +659,10 @@ def merge_cell_notification(if current.output is None:current.output = previous.output+ # UNSET means "unchanged" — inherit the previously broadcast hint so a+ # reconnect snapshot keeps the reusability badge. None (explicit clear) and+ # concrete values are left as-is.+ if current.serialization is msgspec.UNSET:+ current.serialization = previous.serialization+return currentdiff --git a/packages/openapi/api.yaml b/packages/openapi/api.yamlindex e854c67893..fa456e642c 100644--- a/packages/openapi/api.yaml+++ b/packages/openapi/api.yaml@@ -380,16 +380,18 @@ components:format: cell-idtype: stringCellNotification:- description: "Updates a cell's state in the frontend.\n\n Only fields that\- \ are set (not None) will update the cell state.\n Omitting a field leaves\- \ that aspect unchanged.\n\n Attributes:\n cell_id: Unique identifier\- \ of the cell being updated.\n output: Cell's output. Use CellOutput.empty()\- \ to clear.\n console: Console messages. Single/list appends, [] clears,\- \ None unchanged.\n status: Execution status (idle/running/stale/queued/disabled-transitively).\n\+ description: "Updates a cell's state in the frontend.\n\n This is a partial\+ \ update: each field carries its own \"unchanged\" semantics,\n documented\+ \ per field below. Most fields treat None as \"unchanged\"; fields\n that\+ \ need to distinguish \"unchanged\" from \"clear\" use msgspec.UNSET for the\n\+ \ former and None for the latter.\n\n Attributes:\n cell_id:\+ \ Unique identifier of the cell being updated.\n output: Cell's output.\+ \ Use CellOutput.empty() to clear.\n console: Console messages. Single/list\+ \ appends, [] clears, None unchanged.\n status: Execution status (idle/running/stale/queued/disabled-transitively).\n\\ stale_inputs: Whether cell has stale inputs from changed dependencies.\n\\ run_id: Execution run ID for tracing. Auto-set from context.\n \- \ serialization: Serialization status (TopLevelHints).\n timestamp:\- \ Creation timestamp, auto-set."+ \ serialization: Top-level reusability hint. UNSET unchanged, None clears,\+ \ str sets.\n timestamp: Creation timestamp, auto-set."properties:cell_id:$ref: '#/components/schemas/CellId'@@ -418,7 +420,6 @@ components:anyOf:- type: string- type: 'null'- default: nullstale_inputs:anyOf:- type: booleandiff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.tsindex 6c43a64a8f..2c2c1d28be 100644--- a/packages/openapi/src/api.ts+++ b/packages/openapi/src/api.ts@@ -3647,8 +3647,10 @@ export interface components {* CellNotification* @description Updates a cell's state in the frontend.*- * Only fields that are set (not None) will update the cell state.- * Omitting a field leaves that aspect unchanged.+ * This is a partial update: each field carries its own "unchanged" semantics,+ * documented per field below. Most fields treat None as "unchanged"; fields+ * that need to distinguish "unchanged" from "clear" use msgspec.UNSET for the+ * former and None for the latter.** Attributes:* cell_id: Unique identifier of the cell being updated.@@ -3657,7 +3659,7 @@ export interface components {* status: Execution status (idle/running/stale/queued/disabled-transitively).* stale_inputs: Whether cell has stale inputs from changed dependencies.* run_id: Execution run ID for tracing. Auto-set from context.- * serialization: Serialization status (TopLevelHints).+ * serialization: Top-level reusability hint. UNSET unchanged, None clears, str sets.* timestamp: Creation timestamp, auto-set.*/CellNotification: {@@ -3673,7 +3675,6 @@ export interface components {output?: null | components["schemas"]["CellOutput"];/** @default null */run_id?: string | null;- /** @default null */serialization?: string | null;/** @default null */stale_inputs?: boolean | null;diff --git a/tests/_runtime/test_runtime.py b/tests/_runtime/test_runtime.pyindex 93f734e907..f3479a27ab 100644--- a/tests/_runtime/test_runtime.py+++ b/tests/_runtime/test_runtime.py@@ -1839,6 +1839,37 @@ except NameError:else:assert cell_notification.run_id is not None+ async def test_serialization_hint_cleared_only_on_demotion(+ self, mocked_kernel: MockedKernel, exec_req: ExecReqProvider+ ) -> None:+ import msgspec++ k = mocked_kernel.k++ def serialization_hints() -> list[str | None]:+ stream = MockStream(mocked_kernel.stream)+ return [+ cn.serialization+ for op in stream.operations+ if op["op"] == "cell-op"+ for cn in [parse_raw(op, CellNotification)]+ if cn.serialization is not msgspec.UNSET+ ]++ # A top-level definition advertises its reusability hint.+ req = exec_req.get("def foo():\n return 1")+ await k.run([req])+ assert serialization_hints() == ["Valid"]++ # Editing it into a plain assignment clears the hint exactly once+ # (an explicit None, not an omitted/UNSET field).+ await k.run([exec_req.get_with_id(req.cell_id, "x = 1")])+ assert serialization_hints() == ["Valid", None]++ # Re-running the now-ordinary cell emits no further serialization op.+ await k.run([exec_req.get_with_id(req.cell_id, "x = 2")])+ assert serialization_hints() == ["Valid", None]+async def test_sync_graph_basic(self, execution_kernel: Kernel) -> None:"""Test basic synchronization: file changes cell B in A→B→C chain.diff --git a/tests/_session/state/test_session_view.py b/tests/_session/state/test_session_view.pyindex d23b9b8b3c..679c7ab580 100644--- a/tests/_session/state/test_session_view.py+++ b/tests/_session/state/test_session_view.py@@ -4,6 +4,8 @@ from __future__ import annotationsfrom typing import Anyfrom unittest.mock import patch+import msgspec+from marimo._ast.cell import RuntimeStateTypefrom marimo._data.models import (Database,@@ -83,6 +85,57 @@ def test_session_view_cell_notification(session_view: SessionView) -> None:assert session_view.cell_notifications[cell_id].status == updated_status+def test_session_view_serialization_hint_survives_status_updates(+ session_view: SessionView,+) -> None:+ # A top-level definition advertises its reusability hint.+ session_view.add_notification(+ CellNotification(cell_id=cell_id, serialization="Valid")+ )+ assert session_view.cell_notifications[cell_id].serialization == "Valid"++ # Subsequent lifecycle updates omit serialization (UNSET) and must not+ # wipe the hint — otherwise a reconnect snapshot loses the badge.+ for status in ("queued", "running", "idle"):+ status_update = CellNotification(cell_id=cell_id, status=status)+ assert status_update.serialization is msgspec.UNSET+ session_view.add_notification(status_update)+ assert (+ session_view.cell_notifications[cell_id].serialization == "Valid"+ )+++def test_session_view_serialization_hint_explicit_clear(+ session_view: SessionView,+) -> None:+ session_view.add_notification(+ CellNotification(cell_id=cell_id, serialization="Valid")+ )+ # An explicit None clears the hint (cell is no longer a top-level def).+ session_view.add_notification(+ CellNotification(cell_id=cell_id, serialization=None)+ )+ assert session_view.cell_notifications[cell_id].serialization is None+++def test_cell_notification_serialization_wire_encoding() -> None:+ # UNSET is omitted (unchanged), None is sent explicitly (clear), a string+ # is sent verbatim (set).+ assert "serialization" not in serialize(CellNotification(cell_id=cell_id))+ assert (+ serialize(CellNotification(cell_id=cell_id, serialization=None))[+ "serialization"+ ]+ is None+ )+ assert (+ serialize(CellNotification(cell_id=cell_id, serialization="Valid"))[+ "serialization"+ ]+ == "Valid"+ )++# Test adding Variables to SessionViewdef test_session_view_variables(session_view: SessionView) -> None:# Create Variables operation