Skip to content

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.

improvement: include mime-type precedence and visibilty rules (#8037)

Myles Scolnickb9deb9820e5c
diff --git a/frontend/src/components/editor/Output.tsx b/frontend/src/components/editor/Output.tsx
index 21a4759a23..c1a584683b 100644
--- a/frontend/src/components/editor/Output.tsx
+++ b/frontend/src/components/editor/Output.tsx
@@ -36,6 +36,7 @@ import type { TopLevelFacetedUnitSpec } from "@/plugins/impl/data-explorer/queri
import { useTheme } from "@/theme/useTheme";
import { Events } from "@/utils/events";
import { invariant } from "@/utils/invariant";
+import { processMimeBundle } from "@/utils/mime-types";
import { Objects } from "@/utils/objects";
import { LazyVegaEmbed } from "../charts/lazy";
import { ChartLoadingState } from "../data-table/charts/components/chart-states";
@@ -268,10 +269,13 @@ const MimeBundleOutputRenderer: React.FC<{
const metadata = mimebundle[METADATA_KEY];
// Filter out metadata from the mime entries and type narrow
- const mimeEntries = Objects.entries(mimebundle as Record<string, unknown>)
+ const rawEntries = Objects.entries(mimebundle as Record<string, unknown>)
.filter(([key]) => key !== METADATA_KEY)
.map(([mime, data]) => [mime, data] as [MimeType, CellOutput["data"]]);
+ // Apply precedence ordering and hiding rules
+ const { entries: mimeEntries } = processMimeBundle(rawEntries);
+
// If there is none, return null
const first = mimeEntries[0]?.[0];
if (!first) {
@@ -285,7 +289,7 @@ const MimeBundleOutputRenderer: React.FC<{
cellId={cellId}
message={{
channel: channel,
- data: mimebundle[first],
+ data: mimeEntries[0][1],
mimetype: first,
}}
metadata={metadata?.[first]}
@@ -293,14 +297,6 @@ const MimeBundleOutputRenderer: React.FC<{
);
}
- // Sort HTML first
- mimeEntries.sort(([mimeA], [_mimeB]) => {
- if (mimeA === "text/html") {
- return -1;
- }
- return 0;
- });
-
return (
<Tabs defaultValue={first} orientation="vertical">
<div className="flex">
diff --git a/frontend/src/utils/__tests__/mime-types.test.ts b/frontend/src/utils/__tests__/mime-types.test.ts
new file mode 100644
index 0000000000..60ea5a9f1c
--- /dev/null
+++ b/frontend/src/utils/__tests__/mime-types.test.ts
@@ -0,0 +1,326 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { describe, expect, it } from "vitest";
+import type { MimeType } from "@/components/editor/Output";
+import {
+ applyHidingRules,
+ createMimeConfig,
+ getDefaultMimeConfig,
+ processMimeBundle,
+ sortByPrecedence,
+} from "../mime-types";
+
+/** Helper to build a hiding rules Map inline */
+function hidingRules(
+ rules: Record<string, MimeType[]>,
+): ReadonlyMap<MimeType, ReadonlySet<MimeType>> {
+ const map = new Map<MimeType, ReadonlySet<MimeType>>();
+ for (const [trigger, toHide] of Object.entries(rules)) {
+ map.set(trigger as MimeType, new Set(toHide));
+ }
+ return map;
+}
+
+/** Helper to build a precedence Map inline */
+function precedenceMap(types: MimeType[]): ReadonlyMap<MimeType, number> {
+ const map = new Map<MimeType, number>();
+ types.forEach((mime, i) => map.set(mime, i));
+ return map;
+}
+
+describe("mime-types", () => {
+ describe("applyHidingRules", () => {
+ it("should return all visible when no rules match", () => {
+ const mimeTypes = new Set<MimeType>(["text/plain", "text/markdown"]);
+ const rules = hidingRules({ "text/html": ["image/png"] });
+
+ const result = applyHidingRules(mimeTypes, rules);
+
+ expect(result.visible).toEqual(new Set(["text/plain", "text/markdown"]));
+ expect(result.hidden.size).toBe(0);
+ });
+
+ it("should hide mime types when trigger is present", () => {
+ const mimeTypes = new Set<MimeType>([
+ "text/html",
+ "image/png",
+ "text/plain",
+ ]);
+ const rules = hidingRules({ "text/html": ["image/png"] });
+
+ const result = applyHidingRules(mimeTypes, rules);
+
+ expect(result.visible).toEqual(new Set(["text/html", "text/plain"]));
+ expect(result.hidden).toEqual(new Set(["image/png"]));
+ });
+
+ it("should not hide markdown when html is present (per requirements)", () => {
+ const mimeTypes = new Set<MimeType>([
+ "text/html",
+ "text/markdown",
+ "image/png",
+ ]);
+ const rules = hidingRules({ "text/html": ["image/png"] });
+
+ const result = applyHidingRules(mimeTypes, rules);
+
+ expect(result.visible.has("text/markdown")).toBe(true);
+ expect(result.visible.has("text/html")).toBe(true);
+ expect(result.hidden.has("image/png")).toBe(true);
+ });
+
+ it("should handle multiple matching rules", () => {
+ const mimeTypes = new Set<MimeType>([
+ "text/html",
+ "application/vnd.vegalite.v5+json",
+ "image/png",
+ "image/jpeg",
+ ]);
+ const rules = hidingRules({
+ "text/html": ["image/png"],
+ "application/vnd.vegalite.v5+json": ["image/jpeg"],
+ });
+
+ const result = applyHidingRules(mimeTypes, rules);
+
+ expect(result.hidden).toEqual(new Set(["image/png", "image/jpeg"]));
+ expect(result.visible).toEqual(
+ new Set(["text/html", "application/vnd.vegalite.v5+json"]),
+ );
+ });
+
+ it("should handle empty mime types", () => {
+ const mimeTypes = new Set<MimeType>();
+ const rules = hidingRules({ "text/html": ["image/png"] });
+
+ const result = applyHidingRules(mimeTypes, rules);
+
+ expect(result.visible.size).toBe(0);
+ expect(result.hidden.size).toBe(0);
+ });
+
+ it("should handle empty rules", () => {
+ const mimeTypes = new Set<MimeType>(["text/html", "image/png"]);
+ const rules = hidingRules({});
+
+ const result = applyHidingRules(mimeTypes, rules);
+
+ expect(result.visible).toEqual(mimeTypes);
+ expect(result.hidden.size).toBe(0);
+ });
+
+ it("should hide a type that is also a trigger if configured", () => {
+ const mimeTypes = new Set<MimeType>(["text/html", "text/plain"]);
+ const rules = hidingRules({ "text/html": ["text/html"] });
+
+ const result = applyHidingRules(mimeTypes, rules);
+
+ expect(result.hidden.has("text/html")).toBe(true);
+ });
+
+ it("should not hide types that are not present", () => {
+ const mimeTypes = new Set<MimeType>(["text/html"]);
+ const rules = hidingRules({
+ "text/html": ["image/png", "image/jpeg"],
+ });
+
+ const result = applyHidingRules(mimeTypes, rules);
+
+ expect(result.hidden.size).toBe(0);
+ expect(result.visible).toEqual(new Set(["text/html"]));
+ });
+ });
+
+ describe("sortByPrecedence", () => {
+ it("should sort entries by precedence order", () => {
+ const entries: Array<[MimeType, string]> = [
+ ["text/plain", "plain"],
+ ["text/html", "html"],
+ ["image/png", "png"],
+ ];
+
+ const result = sortByPrecedence(
+ entries,
+ precedenceMap(["text/html", "image/png", "text/plain"]),
+ );
+
+ expect(result.map(([m]) => m)).toEqual([
+ "text/html",
+ "image/png",
+ "text/plain",
+ ]);
+ });
+
+ it("should place unknown mime types at the end", () => {
+ const entries: Array<[MimeType, string]> = [
+ ["text/plain", "plain"],
+ ["text/html", "html"],
+ ["application/json", "json"],
+ ];
+
+ const result = sortByPrecedence(entries, precedenceMap(["text/html"]));
+
+ expect(result[0][0]).toBe("text/html");
+ expect(result.slice(1).map(([m]) => m)).toEqual([
+ "text/plain",
+ "application/json",
+ ]);
+ });
+
+ it("should handle empty entries", () => {
+ const result = sortByPrecedence([], precedenceMap(["text/html"]));
+
+ expect(result).toEqual([]);
+ });
+
+ it("should handle empty precedence", () => {
+ const entries: Array<[MimeType, string]> = [
+ ["text/plain", "plain"],
+ ["text/html", "html"],
+ ];
+
+ const result = sortByPrecedence(entries, precedenceMap([]));
+
+ expect(result.map(([m]) => m)).toEqual(["text/plain", "text/html"]);
+ });
+
+ it("should not mutate original array", () => {
+ const entries: Array<[MimeType, string]> = [
+ ["text/plain", "plain"],
+ ["text/html", "html"],
+ ];
+ const original = [...entries];
+
+ sortByPrecedence(entries, precedenceMap(["text/html", "text/plain"]));
+
+ expect(entries).toEqual(original);
+ });
+ });
+
+ describe("processMimeBundle", () => {
+ it("should filter and sort mime entries", () => {
+ const entries: Array<[MimeType, string]> = [
+ ["text/plain", "plain"],
+ ["text/html", "html"],
+ ["image/png", "png"],
+ ];
+
+ const config = createMimeConfig({
+ precedence: ["text/html", "text/plain"],
+ hidingRules: { "text/html": ["image/png"] },
+ });
+
+ const result = processMimeBundle(entries, config);
+
+ expect(result.entries.map(([m]) => m)).toEqual([
+ "text/html",
+ "text/plain",
+ ]);
+ expect(result.hidden).toEqual(["image/png"]);
+ });
+
+ it("should handle empty entries", () => {
+ const result = processMimeBundle([]);
+
+ expect(result.entries).toEqual([]);
+ expect(result.hidden).toEqual([]);
+ });
+
+ it("should use default config when not provided", () => {
+ const entries: Array<[MimeType, string]> = [
+ ["text/html", "html"],
+ ["image/png", "png"],
+ ["text/markdown", "md"],
+ ];
+
+ const result = processMimeBundle(entries);
+
+ expect(result.entries.map(([m]) => m)).not.toContain("image/png");
+ expect(result.entries.map(([m]) => m)).toContain("text/markdown");
+ });
+
+ it("should preserve data associated with mime types", () => {
+ const htmlData = { content: "<h1>Hello</h1>" };
+ const entries: Array<[MimeType, typeof htmlData]> = [
+ ["text/html", htmlData],
+ ];
+
+ const result = processMimeBundle(entries);
+
+ expect(result.entries[0][1]).toBe(htmlData);
+ });
+
+ it("should sort by precedence after filtering", () => {
+ const entries: Array<[MimeType, string]> = [
+ ["text/plain", "plain"],
+ ["text/markdown", "md"],
+ ["text/html", "html"],
+ ];
+
+ const result = processMimeBundle(entries);
+
+ expect(result.entries[0][0]).toBe("text/html");
+ });
+ });
+
+ describe("getDefaultMimeConfig", () => {
+ const config = getDefaultMimeConfig();
+
+ it("should have text/html as highest precedence", () => {
+ expect(config.precedence.get("text/html")).toBe(0);
+ });
+
+ it("should hide image types when html is present", () => {
+ const htmlHides = config.hidingRules.get("text/html");
+
+ expect(htmlHides).toBeDefined();
+ expect(htmlHides?.has("image/png")).toBe(true);
+ expect(htmlHides?.has("image/jpeg")).toBe(true);
+ });
+
+ it("should NOT hide markdown when html is present", () => {
+ const htmlHides = config.hidingRules.get("text/html");
+
+ expect(htmlHides?.has("text/markdown")).toBeFalsy();
+ });
+
+ it("should hide images when vega charts are present", () => {
+ const vegaHides = config.hidingRules.get(
+ "application/vnd.vegalite.v5+json",
+ );
+
+ expect(vegaHides).toBeDefined();
+ expect(vegaHides?.has("image/png")).toBe(true);
+ });
+
+ it("should return the same instance on repeated calls", () => {
+ expect(getDefaultMimeConfig()).toBe(config);
+ });
+ });
+
+ describe("createMimeConfig", () => {
+ it("should compile precedence array into a Map", () => {
+ const config = createMimeConfig({
+ precedence: ["text/html", "image/png"],
+ hidingRules: {},
+ });
+
+ expect(config.precedence.get("text/html")).toBe(0);
+ expect(config.precedence.get("image/png")).toBe(1);
+ expect(config.precedence.has("text/plain")).toBe(false);
+ });
+
+ it("should compile hiding rules into Map<MimeType, Set>", () => {
+ const config = createMimeConfig({
+ precedence: [],
+ hidingRules: {
+ "text/html": ["image/png", "image/jpeg"],
+ },
+ });
+
+ const htmlHides = config.hidingRules.get("text/html");
+ expect(htmlHides).toBeInstanceOf(Set);
+ expect(htmlHides?.has("image/png")).toBe(true);
+ expect(htmlHides?.has("image/jpeg")).toBe(true);
+ });
+ });
+});
diff --git a/frontend/src/utils/mime-types.ts b/frontend/src/utils/mime-types.ts
new file mode 100644
index 0000000000..603f4a368e
--- /dev/null
+++ b/frontend/src/utils/mime-types.ts
@@ -0,0 +1,181 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type { MimeType } from "@/components/editor/Output";
+import { once } from "./once";
+
+/**
+ * Configuration for mime type precedence and filtering.
+ * Uses Map/Set for O(1) lookups at runtime.
+ */
+export interface MimeTypeConfig {
+ /**
+ * Pre-computed precedence map: mime type -> sort index.
+ * Lower index = higher priority. Types not in the map are placed at the end.
+ */
+ precedence: ReadonlyMap<MimeType, number>;
+
+ /**
+ * Hiding rules: trigger mime type -> set of mime types to hide.
+ * When the key mime type is present, all mime types in the value set are hidden.
+ */
+ hidingRules: ReadonlyMap<MimeType, ReadonlySet<MimeType>>;
+}
+
+/**
+ * Result of processing mime types through the filtering and sorting pipeline.
+ */
+export interface ProcessedMimeTypes<T> {
+ /** The filtered and sorted mime entries */
+ entries: Array<[MimeType, T]>;
+ /** Mime types that were hidden by rules */
+ hidden: MimeType[];
+}
+
+/**
+ * Creates a compiled MimeTypeConfig from readable arrays.
+ *
+ * @example
+ * ```ts
+ * const config = createMimeConfig({
+ * precedence: ["text/html", "image/png", "text/plain"],
+ * hidingRules: {
+ * "text/html": ["image/png", "image/jpeg"],
+ * },
+ * });
+ * ```
+ */
+export function createMimeConfig(input: {
+ precedence: MimeType[];
+ hidingRules: Record<string, MimeType[]>;
+}): MimeTypeConfig {
+ const precedence = new Map<MimeType, number>();
+ for (let i = 0; i < input.precedence.length; i++) {
+ precedence.set(input.precedence[i], i);
+ }
+
+ const hidingRules = new Map<MimeType, ReadonlySet<MimeType>>();
+ for (const [trigger, toHide] of Object.entries(input.hidingRules)) {
+ hidingRules.set(trigger as MimeType, new Set(toHide));
+ }
+
+ return { precedence, hidingRules };
+}
+
+/**
+ * Default configuration for mime type handling.
+ * Lazily compiled on first access.
+ *
+ * Design rationale:
+ * - text/html typically contains rich rendered output and should take precedence
+ * - When text/html is present, image fallbacks (png, jpeg, etc.) are often redundant
+ * static renders and should be hidden to reduce UI clutter
+ * - text/markdown should NOT be hidden by text/html as they serve different purposes
+ * - Vega charts should remain visible as they provide interactivity
+ */
+export const getDefaultMimeConfig = once((): MimeTypeConfig => {
+ const IMAGE_FALLBACKS: MimeType[] = ["image/png", "image/jpeg", "image/gif"];
+
+ return createMimeConfig({
+ precedence: [
+ "text/html",
+ "application/vnd.vegalite.v6+json",
+ "application/vnd.vegalite.v5+json",
+ "application/vnd.vega.v6+json",
+ "application/vnd.vega.v5+json",
+ "image/svg+xml",
+ "image/png",
+ "image/jpeg",
+ "image/gif",
+ "text/markdown",
+ "text/latex",
+ "text/csv",
+ "application/json",
+ "text/plain",
+ "video/mp4",
+ "video/mpeg",
+ ],
+ hidingRules: {
+ // When HTML is present, hide static image fallbacks
+ "text/html": [
+ ...IMAGE_FALLBACKS,
+ "image/avif",
+ "image/bmp",
+ "image/tiff",
+ ],
+ // When Vega charts are present, hide image fallbacks
+ "application/vnd.vegalite.v6+json": IMAGE_FALLBACKS,
+ "application/vnd.vegalite.v5+json": IMAGE_FALLBACKS,
+ "application/vnd.vega.v6+json": IMAGE_FALLBACKS,
+ "application/vnd.vega.v5+json": IMAGE_FALLBACKS,
+ },
+ });
+});
+
+/**
+ * Filters mime types based on hiding rules.
+ */
+export function applyHidingRules(
+ mimeTypes: ReadonlySet<MimeType>,
+ rules: ReadonlyMap<MimeType, ReadonlySet<MimeType>>,
+): { visible: Set<MimeType>; hidden: Set<MimeType> } {
+ const hidden = new Set<MimeType>();
+
+ for (const mime of mimeTypes) {
+ const toHide = rules.get(mime);
+ if (toHide) {
+ for (const hideType of toHide) {
+ if (mimeTypes.has(hideType)) {
+ hidden.add(hideType);
+ }
+ }
+ }
+ }
+
+ const visible = new Set<MimeType>();
+ for (const mime of mimeTypes) {
+ if (!hidden.has(mime)) {
+ visible.add(mime);
+ }
+ }
+
+ return { visible, hidden };
+}
+
+/**
+ * Sorts mime entries according to a precedence map.
+ * Mime types not in the map are placed at the end, preserving their original order.
+ */
+export function sortByPrecedence<T>(
+ entries: Array<[MimeType, T]>,
+ precedence: ReadonlyMap<MimeType, number>,
+): Array<[MimeType, T]> {
+ const unknownPrecedence = precedence.size;
+
+ return [...entries].sort((a, b) => {
+ const indexA = precedence.get(a[0]) ?? unknownPrecedence;
+ const indexB = precedence.get(b[0]) ?? unknownPrecedence;
+ return indexA - indexB;
+ });
+}
+
+/**
+ * Main entry point: processes mime entries by applying hiding rules and sorting.
+ */
+export function processMimeBundle<T>(
+ entries: Array<[MimeType, T]>,
+ config: MimeTypeConfig = getDefaultMimeConfig(),
+): ProcessedMimeTypes<T> {
+ if (entries.length === 0) {
+ return { entries: [], hidden: [] };
+ }
+
+ const mimeTypes = new Set(entries.map(([mime]) => mime));
+ const { visible, hidden } = applyHidingRules(mimeTypes, config.hidingRules);
+ const filteredEntries = entries.filter(([mime]) => visible.has(mime));
+ const sortedEntries = sortByPrecedence(filteredEntries, config.precedence);
+
+ return {
+ entries: sortedEntries,
+ hidden: Array.from(hidden),
+ };
+}