Bump 0.2.1

Author: davy39

README.md

@@ -1,8 +1,9 @@
-# ![xeus-ocaml logo](https://raw.githubusercontent.com/davy39/xeus-ocaml/refs/heads/main/share/jupyter/kernels/xocaml/logo-64x64.png) xeus-ocaml
+
+# ![xeus-logo](https://raw.githubusercontent.com/jupyter-xeus/xeus/refs/heads/main/docs/source/xeus.svg) OCAML ![xeus-ocaml logo](https://raw.githubusercontent.com/davy39/xeus-ocaml/refs/heads/main/share/jupyter/kernels/xocaml/logo-64x64.png)
 
 [![CI and Auto-Tagging](https://github.com/davy39/xeus-ocaml/actions/workflows/ci.yml/badge.svg)](https://github.com/davy39/xeus-ocaml/actions/workflows/ci.yml)
 [![Release and Deploy](https://github.com/davy39/xeus-ocaml/actions/workflows/release.yml/badge.svg)](https://github.com/davy39/xeus-ocaml/actions/workflows/release.yml)
-[![GitHub Pages](https://img.shields.io/badge/github--pages-deployed-success)](https://davy39.github.io/xeus-ocaml/)
+[![lite-badge](https://jupyterlite.rtfd.io/en/latest/_static/badge.svg)](https://davy39.github.io/xeus-ocaml/)
 
 `xeus-ocaml` is a Jupyter kernel for the OCaml programming language that runs entirely in the web browser through WebAssembly. It is built on the `xeus-lite` library, a lightweight C++ implementation of the Jupyter protocol for WASM environments.
 
@@ -19,7 +20,49 @@ Experience `xeus-ocaml` firsthand in your browser by visiting the JupyterLite de
 *   **Fully Browser-Based**: Runs entirely in the browser with no server-side installation, powered by WebAssembly.
 *   **Interactive OCaml Toplevel**: Execute OCaml code interactively, with persistent state between cells.
 *   **Rich Language Intelligence**: Provides code completion and inspection (tooltips on hover/Shift+Tab) through an integrated Merlin engine.
-*   **JupyterLite Integration**: Designed for seamless use within the JupyterLite environment.
+*   **Rich Display Support**: Render HTML, Markdown, SVG, JSON, and even complex plots like Vega-Lite directly from your OCaml code.
+
+## 📊 Rich Display and Visualization
+
+The kernel comes with a built-in `Xlib` library that is **automatically opened** on startup, so its functions are immediately available in the global scope. This library provides a simple API for rendering a wide variety of rich outputs in your notebook cells.
+
+Here are some of the key functions available:
+
+| Function                | Description                                                |
+| ----------------------- | ---------------------------------------------------------- |
+| `output_html s`         | Renders a raw HTML string `s`.                             |
+| `output_markdown s`     | Renders a Markdown string `s`.                             |
+| `output_svg s`          | Renders an SVG image from its XML string `s`.              |
+| `output_json s`         | Renders a JSON string `s` as a collapsible tree view.      |
+| `output_vegalite s`     | Renders an interactive Vega-Lite plot from a JSON spec `s`.|
+| `output_png_base64 s`   | Displays a PNG image from a Base64-encoded string `s`.     |
+| `output_jpeg_base64 s`  | Displays a JPEG image from a Base64-encoded string `s`.    |
+
+#### Example Usage
+
+You can call these functions directly in any cell to produce rich outputs.
+
+```ocaml
+(* Render an interactive Vega-Lite chart *)
+let vega_spec = {|
+  {
+    "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
+    "description": "A simple bar chart with embedded data.",
+    "data": {
+      "values": [
+        {"a": "A", "b": 28}, {"a": "B", "b": 55}, {"a": "C", "b": 43},
+        {"a": "D", "b": 91}, {"a": "E", "b": 81}, {"a": "F", "b": 53}
+      ]
+    },
+    "mark": "bar",
+    "encoding": {
+      "x": {"field": "a", "type": "nominal", "axis": {"labelAngle": 0}},
+      "y": {"field": "b", "type": "quantitative"}
+    }
+  }
+|} in
+output_vegalite vega_spec
+```
 
 ## 🏗️ Architecture
 
@@ -64,17 +107,29 @@ This project uses the `pixi` package and environment manager to streamline devel
     ```bash
     pixi run -e ocaml build
     ```
+4.  **Build the Kernel**
+    This build the kernel and create a conda package.
+    ```bash
+    pixi run build-kernel
+    ```
+5.  **Install the kernel**
+    This install the kernel to be used with Jupyterlite.
+    ```bash
+    pixi run install-kernel
+    ```
+6.  **Serve Jupyterlite**
+    This build and serve the Jupyterlite interface.
+    ```bash
+    pixi run install-kernel
+    ```
+    You can now access the local JupyterLite instance in your browser, typically at `http://localhost:8000`.
 
-4.  **Build the WASM Kernel and Serve JupyterLite**
-    This is a convenience command that performs all remaining steps:
-    *   Builds the C++ kernel to WASM using `rattler-build`.
-    *   Packages the kernel and `xocaml.js` into a conda package.
-    *   Installs the package into a local environment.
-    *   Builds and launches a local JupyterLite server.
+7.  **All in one command**
+    This is a convenience command that performs all steps:
     ```bash
     pixi run build-all-serve
     ```
-    You can now access the local JupyterLite instance in your browser, typically at `http://localhost:8000`.
+
 
 ## 🧪 Testing
 
@@ -91,6 +146,7 @@ pixi run -e test test
 -   [x] Interactive code execution via the `js_of_ocaml` toplevel.
 -   [x] Code completion powered by an in-browser Merlin instance.
 -   [x] Code inspection for tooltips (Shift+Tab) and the inspector panel.
+-   [x] **Rich Outputs**: Display HTML, Markdown, SVG, JSON, and Vega-Lite plots directly from OCaml code using the auto-opened `Xlib` module.
 
 ### Future Work
 -   [ ] **Library Management**: Implement a mechanism to dynamically fetch and load pre-compiled OCaml libraries from within a notebook session (e.g., via `#require`).

ocaml/dune

@@ -7,4 +7,3 @@
 (alias
  (name js)
  (deps xocaml.js))
-

ocaml/src/protocol/protocol.ml

@@ -36,6 +36,8 @@ type output =
   | Stdout of string
   | Stderr of string
   | Value of string
+  | DisplayData of Yojson.Safe.t
+
 [@@deriving yojson]
 
 type completions = {

ocaml/src/xlib/dune

@@ -0,0 +1,9 @@
+(library
+ (name xlib)
+ (public_name xocaml.lib)
+ ; (preprocess (pps ppx_deriving_yojson))
+ (libraries
+  xocaml.protocol
+  yojson
+ )
+  (flags (:standard -bin-annot)))

ocaml/src/xlib/xlib.ml

@@ -0,0 +1,79 @@
+(* A mutable list to store outputs generated by user functions. *)
+let extra_outputs = ref []
+
+(* Internal function to add an output to the list. *)
+let add_output output =
+  extra_outputs := output :: !extra_outputs
+
+(* Function to be called by the toplevel to retrieve and clear outputs for the last execution. *)
+let get_and_clear_outputs () =
+  let result = List.rev !extra_outputs in
+  extra_outputs := [];
+  result
+
+(**
+ * Generic helper to create a single-MIME-type display data object and add it to the output list.
+ *)
+let create_and_add_display_data mime_type content =
+  let data = `Assoc [(mime_type, content)] in
+  add_output (Protocol.DisplayData data)
+
+(* The most generic function, exposed to the user. *)
+let output_display_data data =
+  add_output (Protocol.DisplayData data)
+
+(* --- Text-based formats --- *)
+
+let output_html s =
+  create_and_add_display_data "text/html" (`String s)
+
+let output_markdown s =
+  create_and_add_display_data "text/markdown" (`String s)
+
+let output_latex s =
+  create_and_add_display_data "text/latex" (`String s)
+
+let output_svg s =
+  create_and_add_display_data "image/svg+xml" (`String s)
+
+(* --- JSON-based formats --- *)
+(* For these, the frontend expects a JSON object, not a string containing JSON.
+   So we must parse the string into a Yojson.Safe.t value first. *)
+
+let output_json s =
+  try
+    let json_val = Yojson.Safe.from_string s in
+    create_and_add_display_data "application/json" json_val
+  with Yojson.Json_error msg ->
+    let err_msg = Printf.sprintf "JSON parsing error: %s" msg in
+    add_output (Protocol.Stderr err_msg)
+
+let output_vegalite s =
+  try
+    let json_val = Yojson.Safe.from_string s in
+    create_and_add_display_data "application/vnd.vegalite.v5+json" json_val
+  with Yojson.Json_error msg ->
+    let err_msg = Printf.sprintf "Vega-Lite JSON parsing error: %s" msg in
+    add_output (Protocol.Stderr err_msg)
+
+let output_vega s =
+  try
+    let json_val = Yojson.Safe.from_string s in
+    create_and_add_display_data "application/vnd.vega.v5+json" json_val
+  with Yojson.Json_error msg ->
+    let err_msg = Printf.sprintf "Vega JSON parsing error: %s" msg in
+    add_output (Protocol.Stderr err_msg)
+
+(* --- Binary formats (via Base64) --- *)
+
+let output_png_base64 s =
+  create_and_add_display_data "image/png" (`String s)
+
+let output_jpeg_base64 s =
+  create_and_add_display_data "image/jpeg" (`String s)
+
+let output_gif_base64 s =
+  create_and_add_display_data "image/gif" (`String s)
+
+let output_pdf_base64 s =
+  create_and_add_display_data "application/pdf" (`String s)

ocaml/src/xlib/xlib.mli

@@ -0,0 +1,46 @@
+(**
+ * Internal function for the toplevel to retrieve and clear outputs.
+ * This is not intended for direct use by end-users.
+ *)
+val get_and_clear_outputs : unit -> Protocol.output list
+
+(**
+ * Renders a full MIME bundle as a cell output. This is the most flexible
+ * function for creating rich output.
+ * The data should be a Yojson.Safe.t object, e.g.,
+ * `Assoc [("text/plain", `String "plain"); ("text/html", `String "<b>html</b>")]
+ *)
+val output_display_data : Yojson.Safe.t -> unit
+
+(** Renders a raw HTML string as a cell output. *)
+val output_html : string -> unit
+
+(** Renders a raw Markdown string as a cell output. *)
+val output_markdown : string -> unit
+
+(** Renders a raw LaTeX string as a cell output (for equations). *)
+val output_latex : string -> unit
+
+(** Renders a raw SVG image string as a cell output. *)
+val output_svg : string -> unit
+
+(** Renders a JSON string as a collapsible tree view in the output. *)
+val output_json : string -> unit
+
+(** Renders a PNG image from a Base64-encoded string. *)
+val output_png_base64 : string -> unit
+
+(** Renders a JPEG image from a Base64-encoded string. *)
+val output_jpeg_base64 : string -> unit
+
+(** Renders a GIF image from a Base64-encoded string. *)
+val output_gif_base64 : string -> unit
+
+(** Renders an inline PDF document from a Base64-encoded string. *)
+val output_pdf_base64 : string -> unit
+
+(** Renders an interactive Vega-Lite plot from a JSON spec string. *)
+val output_vegalite : string -> unit
+
+(** Renders an interactive Vega plot from a JSON spec string. *)
+val output_vega : string -> unit

ocaml/src/xmerlin/dynamic/dune

@@ -1,14 +1,14 @@
-(data_only_dirs stdlib)
-
 (rule
  (target dynamic_modules.ml)
  (deps
   gen_dynamic.ml
+  (alias ./stdlib/merlin_files)
   (glob_files stdlib/*.cmi))
  (action
   (run ocaml %{dep:gen_dynamic.ml})))
 
 (library
  (name dynamic_modules)
  (public_name xocaml.xmerlin.dynamic_modules)
- (modules dynamic_modules))
+ (modules dynamic_modules))
+

ocaml/src/xmerlin/dynamic/gen_dynamic.ml

@@ -18,6 +18,7 @@ let () =
                 | ["stdlib"] -> "Stdlib" :: acc
                 | ["stdlib"; ""; mod_part] when mod_part <> "" ->
                     String.capitalize_ascii mod_part :: acc
+                | ["xlib"] -> "Xlib" :: acc
                 | _ -> acc
               else acc)
             [] files

ocaml/src/xmerlin/dynamic/stdlib/dune

@@ -0,0 +1,21 @@
+
+(rule
+(alias merlin_files)
+ (mode promote) 
+ (target xlib.cmi)
+ (action
+  (copy %{lib:xocaml.lib:xlib.cmi} %{target})))
+
+(rule
+(alias merlin_files)
+ (mode promote) 
+ (target xlib.cmt)
+ (action
+  (copy %{lib:xocaml.lib:xlib.cmt} %{target})))
+
+(rule
+(alias merlin_files)
+ (mode promote) 
+ (target xlib.cmti)
+ (action
+  (copy %{lib:xocaml.lib:xlib.cmti} %{target})))