@marimo-team/frontend 0.25.3-dev141 → 0.25.3-dev3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marimo-team/frontend",
-  "version": "0.25.3-dev141",
+  "version": "0.25.3-dev3",
   "main": "dist/main.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -183,7 +183,9 @@
     "preview:islands": "cross-env VITE_MARIMO_VERSION='0.4.6' VITE_MARIMO_ISLANDS=true vite --config islands/vite.config.mts build",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
-    "sync-katex-css": "node --experimental-strip-types scripts/sync-katex-css.ts"
+    "sync-katex-css": "node --experimental-strip-types scripts/sync-katex-css.ts",
+    "codegen": "node --experimental-strip-types scripts/generate-host-protocol.ts",
+    "codegen:check": "node --experimental-strip-types scripts/generate-host-protocol.ts --check"
   },
   "peerDependencies": {
     "react": "^17 || ^18 || ^19",
@@ -212,6 +214,7 @@
     "jsdom": "^24.1.3",
     "msw": "^2.15.0",
     "npm-run-all2": "^6.2.6",
+    "orval": "8.40.0",
     "oxc-transform-react": "0.145.0",
     "oxfmt": "^0.68.0",
     "oxlint": "^1.83.0",

package/src/__tests__/host-imports.test.ts

@@ -0,0 +1,100 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import NodeChildProcess from "node:child_process";
+import NodeFs from "node:fs";
+import NodeOs from "node:os";
+import NodePath from "node:path";
+import NodeUrl from "node:url";
+import { expect, it } from "vitest";
+import { z } from "zod";
+
+it("enforces host dependencies for runtime and type imports", () => {
+  const frontend = NodeUrl.fileURLToPath(
+    new NodeUrl.URL("../../", import.meta.url),
+  );
+  const directory = NodeFs.mkdtempSync(
+    NodePath.join(NodeOs.tmpdir(), "host-imports-"),
+  );
+  const files = {
+    "src/core/host/allowed.ts": `
+      import { atom } from "jotai/vanilla";
+      import { z } from "zod";
+      import { Logger } from "@/utils/Logger";
+      import type { Document } from "./document";
+      export * from "@/core/host/events";
+      type Event = import("./events").NotebookEvent;
+      void import("./protocol");
+    `,
+    "src/core/host/protocol.ts": `
+      import type { NotificationMessage as A } from "../kernel/messages";
+      import { type NotificationMessage as B } from "@/core/kernel/messages";
+      import { NotificationMessage as C } from "../kernel/messages";
+      import type { NotificationPayload } from "../kernel/messages";
+    `,
+    "src/core/host/forbidden.ts": `
+      import { useEffect } from "react";
+      import type { NotificationMessage } from "../kernel/messages";
+      export * from "../kernel/messages";
+      export { Logger } from "@/utils/Logger/../other";
+      void import("../kernel/messages");
+      type Message = import("../kernel/messages").NotificationMessage;
+      const module = require("../kernel/messages");
+      void import(module);
+      import "./__tests__/allowed";
+      import "./allowed.test";
+    `,
+    "src/core/host/__tests__/allowed.ts": `import { useEffect } from "react";`,
+    "src/core/host/allowed.test.ts": `import { useEffect } from "react";`,
+    "src/core/host/allowed.spec.ts": `import { useEffect } from "react";`,
+    "src/core/websocket/allowed.ts": `import { useEffect } from "react";`,
+  };
+  try {
+    for (const [path, source] of Object.entries(files)) {
+      const destination = NodePath.join(directory, path);
+      NodeFs.mkdirSync(NodePath.dirname(destination), { recursive: true });
+      NodeFs.writeFileSync(destination, source);
+    }
+    const result = NodeChildProcess.spawnSync(
+      NodePath.join(frontend, "node_modules/.bin/oxlint"),
+      [
+        "--config",
+        NodePath.join(frontend, ".oxlintrc.json"),
+        "--format",
+        "json",
+        directory,
+      ],
+      { cwd: frontend, encoding: "utf8" },
+    );
+    const report = z
+      .object({
+        diagnostics: z.array(
+          z.object({
+            severity: z.string(),
+            filename: z.string(),
+            labels: z.array(z.object({ span: z.object({ line: z.number() }) })),
+          }),
+        ),
+      })
+      .parse(JSON.parse(result.stdout));
+    const errors = report.diagnostics.filter(
+      (diagnostic) => diagnostic.severity === "error",
+    );
+    expect(
+      errors
+        .map((error) => ({
+          file: NodePath.basename(error.filename),
+          line: error.labels[0].span.line,
+        }))
+        .toSorted((a, b) => a.file.localeCompare(b.file) || a.line - b.line),
+    ).toEqual([
+      ...[2, 3, 4, 5, 6, 7, 8, 9, 10, 11].map((line) => ({
+        file: "forbidden.ts",
+        line,
+      })),
+      ...[2, 3, 4, 5].map((line) => ({ file: "protocol.ts", line })),
+    ]);
+    expect(result.status).toBe(1);
+  } finally {
+    NodeFs.rmSync(directory, { recursive: true, force: true });
+  }
+});

package/src/core/host/AGENTS.md

@@ -0,0 +1,6 @@
+# Host core
+
+Production code may import host modules, `jotai/vanilla`, `zod`, and
+`@/utils/Logger`. Enforced by `marimo/host-imports`. Tests are exempt.
+
+Define interfaces here and inject application behavior through adapters.

package/src/core/host/__tests__/protocol.test.ts

@@ -0,0 +1,214 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import NodeFs from "node:fs";
+import NodeUrl from "node:url";
+import { describe, expect, expectTypeOf, it } from "vitest";
+import * as Protocol from "../protocol";
+
+const fixtures = new NodeUrl.URL(
+  "../../../../../protocols/host/fixtures/",
+  import.meta.url,
+);
+
+function readFixture(name: string): unknown {
+  return JSON.parse(
+    NodeFs.readFileSync(new NodeUrl.URL(name, fixtures), "utf8"),
+  );
+}
+
+const records = {
+  "record.json": Protocol.HostRecord,
+  "cell.json": Protocol.Cell,
+  "analysis.json": Protocol.Analysis,
+  "diagnostic.json": Protocol.Error,
+  "edit.json": Protocol.EditRequest,
+  "edit-conflict-request.json": Protocol.EditRequest,
+  "edit-response.json": Protocol.EditResponse,
+  "execution-restored.json": Protocol.Execution,
+  "run-cells-request.json": Protocol.RunRequest,
+};
+
+describe("host protocol fixtures", () => {
+  it.each(Object.entries(records))("parses %s unchanged", (name, schema) => {
+    const input = readFixture(name);
+    const original = structuredClone(input);
+    expect(schema.parse(input)).toEqual(original);
+    expect(input).toEqual(original);
+  });
+
+  it.each(NodeFs.readdirSync(new NodeUrl.URL("problems/", fixtures)))(
+    "parses problem %s",
+    (name) => {
+      const input = readFixture(`problems/${name}`);
+      expect(Protocol.Problem.parse(input)).toEqual(input);
+    },
+  );
+
+  it.each(NodeFs.readdirSync(fixtures).filter((name) => name.endsWith(".sse")))(
+    "parses events in %s unchanged",
+    (name) => {
+      const stream = NodeFs.readFileSync(
+        new NodeUrl.URL(name, fixtures),
+        "utf8",
+      );
+      let count = 0;
+      for (const frame of stream.split(/\r?\n\r?\n/)) {
+        const event = /^event: (.+)$/m.exec(frame)?.[1];
+        if (!event && !/^data:/m.test(frame)) {
+          continue;
+        }
+        const data = frame
+          .split(/\r?\n/)
+          .filter((line) => line.startsWith("data:"))
+          .map((line) => line.slice(5).trimStart())
+          .join("\n");
+        const id = /^id: (.+)$/m.exec(frame)?.[1];
+        const payload: unknown = JSON.parse(data);
+        const input = { event, data: payload, ...(id ? { id } : {}) };
+        const original = structuredClone(input);
+        expect(Protocol.Event.parse(input)).toEqual(original);
+        expect(input).toEqual(original);
+        count += 1;
+      }
+      expect(count).toBeGreaterThan(0);
+    },
+  );
+});
+
+describe("host protocol bindings", () => {
+  it("preserves native marimo payloads without interpreting them", () => {
+    expectTypeOf<Protocol.MarimoEvent["data"]["marimo"]>().toBeUnknown();
+    const input = {
+      event: "marimo",
+      id: "42",
+      data: {
+        marimo: {
+          future_payload: { value: Number.NaN },
+        },
+      },
+    };
+    expect(Protocol.Event.parse(input)).toEqual(input);
+  });
+
+  it("accepts additive fields and preserves arbitrary notebook settings", () => {
+    const cell = Protocol.Cell.parse(readFixture("cell.json"));
+    const input = {
+      ...cell,
+      future: { enabled: true },
+      config: { ...cell.config, future: 42 },
+    };
+    const original = structuredClone(input);
+    expect(Protocol.Cell.parse(input)).toEqual(cell);
+    expect(input).toEqual(original);
+
+    const { document } = Protocol.EditResponse.parse(
+      readFixture("edit-response.json"),
+    );
+    const configured = {
+      ...document,
+      app_config: { extension: { values: [1, null, false] } },
+    };
+    expect(Protocol.Document.parse(configured)).toEqual(configured);
+  });
+
+  it("applies the defaults declared for cell inputs", () => {
+    expect(
+      Protocol.CellInput.parse({ id: "c3", code: "x = 1", config: {} }),
+    ).toEqual({
+      id: "c3",
+      code: "x = 1",
+      name: "_",
+      config: {
+        column: null,
+        disabled: false,
+        hide_code: false,
+        expand_output: false,
+      },
+    });
+  });
+
+  it.each(["run_id", "runtime_id", "caused_by"] as const)(
+    "requires the nullable execution field %s",
+    (field) => {
+      const execution = Protocol.Execution.parse(
+        readFixture("execution-restored.json"),
+      );
+      const missing = Object.fromEntries(
+        Object.entries(execution).filter(([key]) => key !== field),
+      );
+      expect(Protocol.Execution.safeParse(missing).success).toBe(false);
+      expect(
+        Protocol.Execution.safeParse({ ...execution, [field]: null }).success,
+      ).toBe(true);
+    },
+  );
+
+  it("preserves snapshot metadata omissions and validates live timestamps", () => {
+    const cell = Protocol.Cell.parse(readFixture("cell.json"));
+    expect(Protocol.CellMessage.parse({ cell })).toEqual({ cell });
+    const message = { cell, time: "2026-01-01T12:00:00+05:30" };
+    expect(Protocol.CellMessage.parse(message)).toEqual(message);
+    for (const time of [
+      null,
+      "yesterday",
+      "2026-02-30T12:00:00Z",
+      "2026-01-01T12:00:00",
+    ]) {
+      expect(Protocol.CellMessage.safeParse({ cell, time }).success).toBe(
+        false,
+      );
+    }
+  });
+
+  it("rejects invalid cell fields without coercing their values", () => {
+    const cell = Protocol.Cell.parse(readFixture("cell.json"));
+    for (const patch of [
+      { id: "" },
+      { code: 42 },
+      { etag: 42 },
+      { version: "2" },
+      { version: 0 },
+      { version: 1.5 },
+      { config: { ...cell.config, disabled: "false" } },
+    ]) {
+      expect(Protocol.Cell.safeParse({ ...cell, ...patch }).success).toBe(
+        false,
+      );
+    }
+    const result = Protocol.Cell.safeParse({ ...cell, code: 42 });
+    expect(result.success).toBe(false);
+    if (result.success) {
+      throw new Error("Expected an invalid cell");
+    }
+    expect(result.error.issues).toEqual([
+      expect.objectContaining({ path: ["code"], code: "invalid_type" }),
+    ]);
+  });
+
+  it("requires the fields of the selected change kind", () => {
+    const change = { kind: "delete_cell", id: "c3", base_etag: "*" };
+    expect(Protocol.Change.parse(change)).toEqual(change);
+    expect(
+      Protocol.Change.safeParse({ kind: "delete_cell", id: "c3" }).success,
+    ).toBe(false);
+    expect(
+      Protocol.Change.safeParse({ ...change, kind: "unknown" }).success,
+    ).toBe(false);
+  });
+
+  it("requires custom payloads while allowing any JSON value", () => {
+    for (const data of [
+      null,
+      false,
+      42,
+      "text",
+      { nested: [1, null, false] },
+    ]) {
+      const custom = { type: "example.event", data };
+      expect(Protocol.Custom.parse(custom)).toEqual(custom);
+    }
+    expect(Protocol.Custom.safeParse({ type: "example.event" }).success).toBe(
+      false,
+    );
+  });
+});