@marimo-team/islands 0.25.2-dev12 → 0.25.2-dev121

package/src/core/websocket/__tests__/useMarimoKernelConnection.hook.test.tsx

@@ -52,7 +52,7 @@ import { useRuntimeManager } from "@/core/runtime/config";
 import { initialRunCompletedAtom } from "../../kernel/state";
 import { connectionAtom, startupProgressAtom } from "../../network/connection";
 import type { SessionId } from "../../kernel/session";
-import { WebSocketClosedReason, WebSocketState } from "../types";
+import { WebSocketClosedReason, ConnectionState } from "../types";
 import type { IConnectionTransport } from "../transports/transport";
 import { useMarimoKernelConnection } from "../useMarimoKernelConnection";
 import { useConnectionTransport } from "../useWebSocket";
@@ -118,7 +118,7 @@ describe("useMarimoKernelConnection.reconnect()", () => {
     isHealthy = vi.fn<() => Promise<boolean>>().mockResolvedValue(true);
     store = createStore();
     store.set(connectionAtom, {
-      state: WebSocketState.CLOSED,
+      state: ConnectionState.CLOSED,
       code: WebSocketClosedReason.KERNEL_DISCONNECTED,
       reason: "kernel not found",
     });
@@ -163,7 +163,7 @@ describe("useMarimoKernelConnection.reconnect()", () => {
     expect(isHealthy).toHaveBeenCalledOnce();
     expect(transport.reconnect).toHaveBeenCalledOnce();
     expect(store.get(connectionAtom)).toEqual({
-      state: WebSocketState.CONNECTING,
+      state: ConnectionState.CONNECTING,
     });
   });
 
@@ -176,7 +176,7 @@ describe("useMarimoKernelConnection.reconnect()", () => {
     expect(isHealthy).toHaveBeenCalledOnce();
     expect(transport.reconnect).not.toHaveBeenCalled();
     expect(store.get(connectionAtom)).toEqual({
-      state: WebSocketState.CLOSED,
+      state: ConnectionState.CLOSED,
       code: WebSocketClosedReason.KERNEL_DISCONNECTED,
       reason: "kernel not found",
     });
@@ -215,7 +215,7 @@ it.each(["kernel-ready", "reconnected"])(
   "waits for %s before marking the session connected",
   async (op) => {
     const store = createStore();
-    store.set(connectionAtom, { state: WebSocketState.CONNECTING });
+    store.set(connectionAtom, { state: ConnectionState.CONNECTING });
     vi.mocked(useConnectionTransport).mockClear();
     vi.mocked(useConnectionTransport).mockReturnValue(
       makeTransport(WebSocket.OPEN),
@@ -229,7 +229,7 @@ it.each(["kernel-ready", "reconnected"])(
     await act(async () => {
       await options.onOpen(new Event("open"));
     });
-    expect(store.get(connectionAtom).state).toBe(WebSocketState.CONNECTING);
+    expect(store.get(connectionAtom).state).toBe(ConnectionState.CONNECTING);
 
     act(() => {
       options.onMessage(
@@ -257,7 +257,7 @@ it.each(["kernel-ready", "reconnected"])(
         }),
       );
     });
-    expect(store.get(connectionAtom).state).toBe(WebSocketState.OPEN);
+    expect(store.get(connectionAtom).state).toBe(ConnectionState.OPEN);
   },
 );
 
@@ -267,7 +267,7 @@ describe("connection notice", () => {
 
   function renderNotice() {
     const store = createStore();
-    store.set(connectionAtom, { state: WebSocketState.CONNECTING });
+    store.set(connectionAtom, { state: ConnectionState.CONNECTING });
     const transport = makeTransport(WebSocket.OPEN);
     vi.mocked(useConnectionTransport).mockReturnValue(transport);
     vi.mocked(useRuntimeManager).mockReturnValue(
@@ -322,14 +322,6 @@ describe("connection notice", () => {
     );
     act(() => vi.advanceTimersByTime(35_000));
     expect(screen.getByText("Elapsed 35s")).toBeInTheDocument();
-    act(() =>
-      store.set(
-        notebookAtom,
-        MockNotebook.notebookState({
-          cellData: { [cellId("test")]: { code: "answer = 42" } },
-        }),
-      ),
-    );
     send({
       op: "startup-progress",
       phase: "starting-kernel",
@@ -338,6 +330,18 @@ describe("connection notice", () => {
     });
     expect(screen.getByRole("status")).toHaveTextContent("Starting kernel");
     expect(screen.getByText("Elapsed 35s")).toBeInTheDocument();
+    act(() =>
+      store.set(
+        notebookAtom,
+        MockNotebook.notebookState({
+          cellData: { [cellId("test")]: { code: "answer = 42" } },
+        }),
+      ),
+    );
+    expect(
+      screen.getByRole("button", { name: "Starting kernel… Open Packages" }),
+    ).toBeVisible();
+    expect(screen.queryByText(/Elapsed/)).not.toBeInTheDocument();
     send({ op: "reconnected" });
     expect(
       screen.queryByRole("region", { name: "Notebook startup" }),
@@ -345,7 +349,7 @@ describe("connection notice", () => {
     act(() => options.onClose(new CloseEvent("close")));
     act(() => vi.advanceTimersByTime(500));
     expect(store.get(connectionAtom)).toEqual({
-      state: WebSocketState.CONNECTING,
+      state: ConnectionState.CONNECTING,
       phase: "reconnecting",
     });
     expect(
@@ -388,7 +392,7 @@ describe("connection notice", () => {
       logs: "Kernel startup output\n",
       log_mode: "replace",
     });
-    expect(store.get(connectionAtom)).toEqual({ state: WebSocketState.OPEN });
+    expect(store.get(connectionAtom)).toEqual({ state: ConnectionState.OPEN });
     expect(store.get(startupProgressAtom)).toEqual({
       phase: "starting-kernel",
       logs: "Kernel startup output\n",
@@ -429,12 +433,9 @@ describe("connection notice", () => {
     ).not.toBeInTheDocument();
   });
 
-  it.each([
-    ["preparing-environment", "Sandbox setup failed"],
-    ["starting-kernel", "Kernel failed to start"],
-  ] as const)(
+  it.each(["preparing-environment", "starting-kernel"] as const)(
     "keeps a %s failure available until the user retries",
-    async (phase, title) => {
+    async (phase) => {
       const { store, transport, options, send } = renderNotice();
       send({ op: "startup-progress", phase, logs: "", log_mode: "replace" });
       const error = "A full diagnostic\nwith <stderr> details";
@@ -445,9 +446,13 @@ describe("connection notice", () => {
           new CloseEvent("close", { reason: "MARIMO_KERNEL_STARTUP_ERROR" }),
         ),
       );
-      expect(screen.getByRole("status")).toHaveTextContent(title);
+      expect(screen.getByRole("status")).toHaveTextContent(
+        "Kernel failed to start",
+      );
       act(() => vi.advanceTimersByTime(30_000));
-      expect(screen.getByRole("status")).toHaveTextContent(title);
+      expect(screen.getByRole("status")).toHaveTextContent(
+        "Kernel failed to start",
+      );
       expect(screen.getByLabelText("Error details")).toHaveTextContent(error, {
         normalizeWhitespace: false,
       });

package/src/core/websocket/__tests__/useMarimoKernelConnection.test.ts

@@ -2,7 +2,7 @@
 
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { Logger } from "@/utils/Logger";
-import { WebSocketClosedReason, WebSocketState } from "../types";
+import { WebSocketClosedReason, ConnectionState } from "../types";
 import { classifyCloseEvent } from "../useMarimoKernelConnection";
 
 function classify(reason: string | undefined) {
@@ -14,7 +14,7 @@ describe("classifyCloseEvent", () => {
     it("retries on empty/undefined reason", () => {
       const decision = classify(undefined);
       expect(decision.kind).toBe("retry");
-      expect(decision.status).toEqual({ state: WebSocketState.CONNECTING });
+      expect(decision.status).toEqual({ state: ConnectionState.CONNECTING });
     });
 
     it("treats unknown reason strings as transient and logs a warning", () => {
@@ -44,7 +44,7 @@ describe("classifyCloseEvent", () => {
       const decision = classify(reason);
       expect(decision.kind).toBe("terminal");
       expect(decision.status).toMatchObject({
-        state: WebSocketState.CLOSED,
+        state: ConnectionState.CLOSED,
         code: WebSocketClosedReason.KERNEL_DISCONNECTED,
       });
       expect(decision).toMatchObject({
@@ -57,7 +57,7 @@ describe("classifyCloseEvent", () => {
       const decision = classify("MARIMO_KERNEL_STARTUP_ERROR");
       expect(decision.kind).toBe("terminal");
       expect(decision.status).toMatchObject({
-        state: WebSocketState.CLOSED,
+        state: ConnectionState.CLOSED,
         code: WebSocketClosedReason.KERNEL_STARTUP_ERROR,
       });
       expect(decision).toMatchObject({
@@ -72,7 +72,7 @@ describe("classifyCloseEvent", () => {
       const decision = classify("MARIMO_TRANSPORT_EXHAUSTED");
       expect(decision.kind).toBe("gave-up");
       expect(decision.status).toEqual({
-        state: WebSocketState.CLOSED,
+        state: ConnectionState.CLOSED,
         code: WebSocketClosedReason.KERNEL_DISCONNECTED,
         reason: "kernel not found",
       });

package/src/core/websocket/connection-utils.ts

@@ -1,66 +1,66 @@
 /* Copyright 2026 Marimo. All rights reserved. */
-import { WebSocketState } from "./types";
+import { ConnectionState } from "./types";
 
 /**
  * Check if the app is in a closed/disconnected state
  */
-export function isAppClosed(state: WebSocketState): boolean {
-  return state === WebSocketState.CLOSED;
+export function isAppClosed(state: ConnectionState): boolean {
+  return state === ConnectionState.CLOSED;
 }
 
 /**
  * Check if the app is in a connecting state
  */
-export function isAppConnecting(state: WebSocketState): boolean {
-  return state === WebSocketState.CONNECTING;
+export function isAppConnecting(state: ConnectionState): boolean {
+  return state === ConnectionState.CONNECTING;
 }
 
 /**
  * Check if the app is in an open/connected state
  */
-export function isAppConnected(state: WebSocketState): boolean {
-  return state === WebSocketState.OPEN;
+export function isAppConnected(state: ConnectionState): boolean {
+  return state === ConnectionState.OPEN;
 }
 
 /**
  * Check if the app is in a closing state
  */
-export function isAppClosing(state: WebSocketState): boolean {
-  return state === WebSocketState.CLOSING;
+export function isAppClosing(state: ConnectionState): boolean {
+  return state === ConnectionState.CLOSING;
 }
 
 /**
  * Check if the app is in a not started state
  */
-export function isAppNotStarted(state: WebSocketState): boolean {
-  return state === WebSocketState.NOT_STARTED;
+export function isAppNotStarted(state: ConnectionState): boolean {
+  return state === ConnectionState.NOT_STARTED;
 }
 
 /**
  * Check if the app is in a state where user interactions should be disabled
  */
-export function isAppInteractionDisabled(state: WebSocketState): boolean {
+export function isAppInteractionDisabled(state: ConnectionState): boolean {
   return (
-    state === WebSocketState.CLOSED ||
-    state === WebSocketState.CLOSING ||
-    state === WebSocketState.CONNECTING
+    state === ConnectionState.CLOSED ||
+    state === ConnectionState.CLOSING ||
+    state === ConnectionState.CONNECTING
   );
 }
 
 /**
  * Get a human-readable tooltip message for the connection state
  */
-export function getConnectionTooltip(state: WebSocketState): string {
+export function getConnectionTooltip(state: ConnectionState): string {
   switch (state) {
-    case WebSocketState.CLOSED:
+    case ConnectionState.CLOSED:
       return "App disconnected";
-    case WebSocketState.CONNECTING:
+    case ConnectionState.CONNECTING:
       return "Connecting to a runtime ...";
-    case WebSocketState.CLOSING:
+    case ConnectionState.CLOSING:
       return "App disconnecting...";
-    case WebSocketState.OPEN:
+    case ConnectionState.OPEN:
       return "";
-    case WebSocketState.NOT_STARTED:
+    case ConnectionState.NOT_STARTED:
       return "Click to connect to a runtime";
     default:
       return "";

package/src/core/websocket/types.ts

@@ -6,8 +6,7 @@ export type ConnectionPhase =
   | NotificationMessageData<"startup-progress">["phase"]
   | "reconnecting";
 
-// TODO: rename to ConnectionState
-export const WebSocketState = {
+export const ConnectionState = {
   NOT_STARTED: "NOT_STARTED",
   CONNECTING: "CONNECTING",
   OPEN: "OPEN",
@@ -15,8 +14,8 @@ export const WebSocketState = {
   CLOSED: "CLOSED",
 } as const;
 
-export type WebSocketState =
-  (typeof WebSocketState)[keyof typeof WebSocketState];
+export type ConnectionState =
+  (typeof ConnectionState)[keyof typeof ConnectionState];
 
 export const WebSocketClosedReason = {
   KERNEL_DISCONNECTED: "KERNEL_DISCONNECTED",
@@ -28,7 +27,7 @@ export type WebSocketClosedReason =
 
 export type ConnectionStatus =
   | {
-      state: typeof WebSocketState.CLOSED;
+      state: typeof ConnectionState.CLOSED;
       code: WebSocketClosedReason;
       /**
        * Human-readable reason for closing the connection.
@@ -37,12 +36,12 @@ export type ConnectionStatus =
       phase?: ConnectionPhase;
     }
   | {
-      state: typeof WebSocketState.CONNECTING;
+      state: typeof ConnectionState.CONNECTING;
       phase?: ConnectionPhase;
     }
   | {
       state:
-        | typeof WebSocketState.OPEN
-        | typeof WebSocketState.CLOSING
-        | typeof WebSocketState.NOT_STARTED;
+        | typeof ConnectionState.OPEN
+        | typeof ConnectionState.CLOSING
+        | typeof ConnectionState.NOT_STARTED;
     };

package/src/core/websocket/useMarimoKernelConnection.tsx

@@ -60,7 +60,11 @@ import {
   handleRemoveUIElements,
 } from "../kernel/handlers";
 import { queryParamHandlers } from "../kernel/queryParamHandlers";
-import type { SessionId } from "../kernel/session";
+import {
+  type SessionId,
+  type StableSessionId,
+  stableSessionIdAtom,
+} from "../kernel/session";
 import { initialRunCompletedAtom, kernelStateAtom } from "../kernel/state";
 import { type LayoutState, useLayoutActions } from "../layout/state";
 import { kioskModeAtom } from "../mode";
@@ -80,7 +84,7 @@ import { isWasm } from "../wasm/utils";
 import {
   type ConnectionStatus,
   WebSocketClosedReason,
-  WebSocketState,
+  ConnectionState,
 } from "./types";
 
 const SUPPORTS_LAZY_KERNELS = true;
@@ -112,7 +116,7 @@ export function classifyCloseEvent(event: { reason?: string }): CloseDecision {
       return {
         kind: "gave-up",
         status: {
-          state: WebSocketState.CLOSED,
+          state: ConnectionState.CLOSED,
           code: WebSocketClosedReason.KERNEL_DISCONNECTED,
           reason: "kernel not found",
         },
@@ -124,7 +128,7 @@ export function classifyCloseEvent(event: { reason?: string }): CloseDecision {
       return {
         kind: "terminal",
         status: {
-          state: WebSocketState.CLOSED,
+          state: ConnectionState.CLOSED,
           code: WebSocketClosedReason.KERNEL_DISCONNECTED,
           reason: "kernel not found",
         },
@@ -134,7 +138,7 @@ export function classifyCloseEvent(event: { reason?: string }): CloseDecision {
       return {
         kind: "terminal",
         status: {
-          state: WebSocketState.CLOSED,
+          state: ConnectionState.CLOSED,
           code: WebSocketClosedReason.KERNEL_DISCONNECTED,
           reason: "not authorized",
         },
@@ -144,7 +148,7 @@ export function classifyCloseEvent(event: { reason?: string }): CloseDecision {
       return {
         kind: "terminal",
         status: {
-          state: WebSocketState.CLOSED,
+          state: ConnectionState.CLOSED,
           code: WebSocketClosedReason.KERNEL_DISCONNECTED,
           reason: "kiosk mode is not available for this session",
         },
@@ -154,7 +158,7 @@ export function classifyCloseEvent(event: { reason?: string }): CloseDecision {
       return {
         kind: "terminal",
         status: {
-          state: WebSocketState.CLOSED,
+          state: ConnectionState.CLOSED,
           code: WebSocketClosedReason.KERNEL_STARTUP_ERROR,
           reason: "Failed to start kernel sandbox",
         },
@@ -171,7 +175,7 @@ export function classifyCloseEvent(event: { reason?: string }): CloseDecision {
 
   return {
     kind: "retry",
-    status: { state: WebSocketState.CONNECTING },
+    status: { state: ConnectionState.CONNECTING },
   };
 }
 
@@ -231,6 +235,7 @@ export function useMarimoKernelConnection(opts: {
     addStartupLog,
   } = useAlertActions();
   const setKioskMode = useSetAtom(kioskModeAtom);
+  const setStableSessionId = useSetAtom(stableSessionIdAtom);
   const setCapabilities = useSetAtom(capabilitiesAtom);
   const runtimeManager = useRuntimeManager();
   const transportType = useAtomValue(connectionTransportTypeAtom);
@@ -251,17 +256,17 @@ export function useMarimoKernelConnection(opts: {
         const { phase } = msg.data;
         updateStartupProgress(msg.data);
         setConnection((previous) =>
-          previous.state === WebSocketState.OPEN ||
-          (previous.state === WebSocketState.CONNECTING &&
+          previous.state === ConnectionState.OPEN ||
+          (previous.state === ConnectionState.CONNECTING &&
             previous.phase === phase)
             ? previous
-            : { state: WebSocketState.CONNECTING, phase },
+            : { state: ConnectionState.CONNECTING, phase },
         );
         return;
       }
       case "kernel-ready": {
         setKernelStartupError(null);
-        setConnection({ state: WebSocketState.OPEN });
+        setConnection({ state: ConnectionState.OPEN });
         setInitialRunCompleted(
           Boolean(msg.data.resumed || msg.data.auto_instantiated),
         );
@@ -284,6 +289,10 @@ export function useMarimoKernelConnection(opts: {
           invalidateDataSourceDiscovery();
         }
         setKioskMode(msg.data.kiosk);
+        setStableSessionId(
+          (msg.data.stable_session_id as StableSessionId | null | undefined) ??
+            null,
+        );
         // A freshly started kernel has no breakpoints of its own; re-push
         // the client's set so they still apply, and clear the stale
         // highlighted line from the previous kernel instance.
@@ -295,6 +304,8 @@ export function useMarimoKernelConnection(opts: {
       case "completed-run":
         setInitialRunCompleted(true);
         return;
+      case "execution":
+        return;
       case "interrupted":
         return;
 
@@ -470,7 +481,7 @@ export function useMarimoKernelConnection(opts: {
 
       case "reconnected":
         setKernelStartupError(null);
-        setConnection({ state: WebSocketState.OPEN });
+        setConnection({ state: ConnectionState.OPEN });
         return;
 
       case "focus-cell":
@@ -515,12 +526,12 @@ export function useMarimoKernelConnection(opts: {
     }
     shouldTryReconnecting.current = true;
     setKernelStartupError(null);
-    setConnection({ state: WebSocketState.CONNECTING });
+    setConnection({ state: ConnectionState.CONNECTING });
     const healthy = await runtimeManager.reconcileFromHealth();
     if (!healthy) {
       shouldTryReconnecting.current = false;
       setConnection({
-        state: WebSocketState.CLOSED,
+        state: ConnectionState.CLOSED,
         code: WebSocketClosedReason.KERNEL_DISCONNECTED,
         reason: "kernel not found",
       });
@@ -596,17 +607,17 @@ export function useMarimoKernelConnection(opts: {
       setConnection((previous) => {
         const status = decision.status;
         if (
-          status.state === WebSocketState.CLOSED &&
+          status.state === ConnectionState.CLOSED &&
           status.code === WebSocketClosedReason.KERNEL_STARTUP_ERROR &&
-          (previous.state === WebSocketState.CONNECTING ||
-            previous.state === WebSocketState.CLOSED)
+          (previous.state === ConnectionState.CONNECTING ||
+            previous.state === ConnectionState.CLOSED)
         ) {
           return { ...status, phase: previous.phase };
         }
         if (
-          status.state === WebSocketState.CONNECTING &&
-          (previous.state === WebSocketState.OPEN ||
-            (previous.state === WebSocketState.CONNECTING &&
+          status.state === ConnectionState.CONNECTING &&
+          (previous.state === ConnectionState.OPEN ||
+            (previous.state === ConnectionState.CONNECTING &&
               previous.phase === "reconnecting"))
         ) {
           return { ...status, phase: "reconnecting" };
@@ -631,7 +642,7 @@ export function useMarimoKernelConnection(opts: {
     onError: (e) => {
       Logger.warn("WebSocket error", e);
       setConnection({
-        state: WebSocketState.CLOSED,
+        state: ConnectionState.CLOSED,
         code: WebSocketClosedReason.KERNEL_DISCONNECTED,
         reason: "kernel not found",
       });

package/src/css/katex-css.test.ts

@@ -0,0 +1,166 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { readFile } from "node:fs/promises";
+import postcss from "postcss";
+import { beforeAll, describe, expect, it } from "vitest";
+import {
+  checkKatexCss,
+  generateKatexCss,
+  readUpstreamCss,
+  stylesheetPath,
+} from "../../scripts/katex-css";
+
+let upstream: string;
+let generated: string;
+
+beforeAll(async () => {
+  upstream = await readUpstreamCss();
+  generated = await generateKatexCss(upstream);
+});
+
+describe("copied KaTeX stylesheet", () => {
+  it("matches the installed package with only documented marimo overrides", async () => {
+    await expect(
+      checkKatexCss(upstream, await readFile(stylesheetPath, "utf8")),
+    ).resolves.toBeUndefined();
+  });
+
+  it.each(["added", "removed", "changed"])(
+    "detects %s upstream rule without a version change",
+    async (change) => {
+      const root = postcss.parse(upstream);
+      if (change === "added") {
+        root.append(
+          postcss.parse(
+            ".katex .upstream-drift-probe { display: inline-block; }",
+          ),
+        );
+      } else {
+        root.walkRules(".katex .mspace", (rule) => {
+          if (change === "removed") {
+            rule.remove();
+          } else {
+            rule.append(postcss.decl({ prop: "color", value: "red" }));
+          }
+        });
+      }
+      await expect(checkKatexCss(root.toString(), generated)).rejects.toThrow(
+        "pnpm sync-katex-css",
+      );
+      const regenerated = await generateKatexCss(root.toString());
+      await checkKatexCss(root.toString(), regenerated);
+    },
+  );
+
+  it.each(["added", "removed", "changed"])(
+    "detects %s local rule",
+    async (change) => {
+      const root = postcss.parse(generated);
+      if (change === "added") {
+        root.append(postcss.parse(".katex .unexpected { display: none; }"));
+      } else {
+        root.walkRules(".katex .mspace", (rule) => {
+          if (change === "removed") {
+            rule.remove();
+          } else {
+            rule.append(postcss.decl({ prop: "color", value: "red" }));
+          }
+        });
+      }
+      await expect(checkKatexCss(upstream, root.toString())).rejects.toThrow(
+        "pnpm sync-katex-css",
+      );
+    },
+  );
+
+  it("preserves math sizing, tag alignment, and equation counters without bundling font faces", () => {
+    const root = postcss.parse(generated);
+    const declarations = (selector: string) => {
+      const values: Record<string, string> = {};
+      root.walkRules(selector, (rule) => {
+        rule.walkDecls((decl) => {
+          values[decl.prop] = decl.value;
+        });
+      });
+      return values;
+    };
+    expect(declarations(".katex")).toEqual({
+      "font-family": '"KaTeX_Main", "Times New Roman", serif',
+      "font-size": "110%",
+      "font-style": "normal",
+      "line-height": "inherit",
+      position: "relative",
+      "text-indent": "0",
+      "text-rendering": "auto",
+    });
+    expect(
+      declarations(".katex-display > .katex > .katex-html > .katex-tag"),
+    ).toEqual({ position: "absolute", right: "0", "text-align": "right" });
+    expect(declarations("body,\n.katex-display")).toEqual({
+      "counter-reset": "katexEqnNo mmlEqnNo",
+    });
+    expect(declarations(".katex .angl")["border-right"]).toBe("0.049em solid");
+    const fontFaces: postcss.AtRule[] = [];
+    root.walkAtRules("font-face", (rule) => {
+      fontFaces.push(rule);
+    });
+    expect(fontFaces).toEqual([]);
+  });
+
+  it.each(["root", "media"])(
+    "preserves SVG rule order and %s scope when upstream adds a competing rule",
+    async (scope) => {
+      const root = postcss.parse(upstream);
+      const svgRules: postcss.Rule[] = [];
+      root.walkRules(".katex svg", (rule) => {
+        svgRules.push(rule);
+      });
+      const secondSvg = svgRules[1];
+      secondSvg.before(postcss.parse(".katex :is(svg) { stroke-width: 3; }"));
+      if (scope === "media") {
+        const media = postcss.atRule({ name: "media", params: "print" });
+        secondSvg.before(media);
+        media.append(secondSvg);
+      }
+
+      const svgCascade = (css: string) => {
+        const rules: {
+          selector: string;
+          scope: string;
+          strokeWidth: string | undefined;
+        }[] = [];
+        postcss.parse(css).walkRules((rule) => {
+          if (
+            rule.selector !== ".katex svg" &&
+            rule.selector !== ".katex :is(svg)"
+          ) {
+            return;
+          }
+          let strokeWidth: string | undefined;
+          rule.walkDecls("stroke-width", (decl) => {
+            strokeWidth = decl.value;
+          });
+          const parent = rule.parent;
+          rules.push({
+            selector: rule.selector,
+            scope:
+              parent?.type === "atrule"
+                ? `${parent.name} ${parent.params}`
+                : "root",
+            strokeWidth,
+          });
+        });
+        return rules;
+      };
+      const regenerated = await generateKatexCss(root.toString());
+      expect(svgCascade(regenerated)).toEqual(svgCascade(root.toString()));
+      await checkKatexCss(root.toString(), regenerated);
+    },
+  );
+
+  it("requires review when an overridden upstream declaration changes", async () => {
+    await expect(
+      generateKatexCss(upstream.replace("line-height:1.2", "line-height:1.3")),
+    ).rejects.toThrow("review overrides");
+  });
+});