Java Notebook

Notebook de Java 17 que corre 100% en el navegador, al estilo Jupyter: celdas de código y markdown. Sin servidor, sin backend, sin instalación. JShell ejecuta el código dentro de una JVM completa compilada a WebAssembly (CheerpJ).

Cómo funciona

Cada pestaña abre una sesión JShell independiente. Al correr una celda, su código se evalúa contra esa sesión y la salida (stdout/stderr) aparece debajo. Variables, clases y métodos declarados en una celda quedan disponibles en las siguientes.

Configuración

Desde el ícono de engranaje en la barra superior:

• Tema: Auto (sigue al sistema), Claro, u Oscuro
• Identación: 2 o 4 espacios
• Modo: Edición (todos los controles visibles) o Lectura (oculta controles de edición)
• Atajos generales: On/Off (default Off). Habilita Ctrl+X/C/V/Z/Delete para cortar, copiar, pegar, deshacer y eliminar celdas cuando el foco está fuera del editor

La configuración se guarda en localStorage. Presionar ? para ver los atajos de teclado disponibles.

Limitaciones

Al correr en el navegador hay algunas diferencias con un JDK de escritorio:

• Scanner / System.in: no hay stdin en el browser
• java.io.File: no hay filesystem
• Algunas excepciones lanzadas por el JVM (división por cero, OOB de arrays) llegan sin mensaje. La clase de la excepción es correcta, pero el detalle ("/ by zero", "Index 3 out of bounds for length 3") queda null. Las excepciones que el usuario lanza con throw sí conservan el mensaje.
• 1 % 0 devuelve 0 en vez de lanzar ArithmeticException (bug del opcode WASM)
• new int[-1] lanza ArithmeticException en vez de NegativeArraySizeException
• La primera ejecución es lenta (entre 5 y 10s) mientras CheerpJ inicializa la JVM
• No hay forma de interrumpir un bucle infinito desde la página. Si una celda se cuelga, cerrá y volvé a abrir la pestaña.

Actualizar ejemplos

Los notebooks de ejemplo están en public/examples/. Para agregar o modificar un ejemplo:

1. Crear o editar el archivo .ipynb en public/examples/
   • Se puede exportar un notebook desde la app con el botón Exportar
2. Agregar la entrada en public/examples/index.json:

   { "name": "Nombre visible en el menú", "filename": "mi-ejemplo.ipynb" }

Para eliminar un ejemplo, borrar el .ipynb y su entrada en index.json. No requiere ninguna herramienta, son archivos estáticos.

---

Desarrollo

Requisitos

• Node.js 24 o superior (viene con npm incluido)

Se recomienda instalar Node.js a través de nvm (Node Version Manager), que permite manejar múltiples versiones fácilmente:

Plataforma	nvm	Instalación
Linux / macOS	nvm-sh/nvm	curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
Windows	nvm-windows	Descargar el instalador desde Releases

Después de instalar nvm:

nvm install 24
nvm use 24

Inicio rápido

git clone git@github.com:Federico-G/java-notebook.git
cd java-notebook

Linux / macOS:

bash start.sh

Windows:

start.bat

Los scripts corren npm install si todavía no hay node_modules/, y arrancan el servidor de desarrollo con npx vite --open. En Windows el .bat delega a PowerShell para que el profile cargue fnm/nvm antes (cmd.exe no lo hace).

Equivalente manual:

npm install
npm run dev

El servidor de desarrollo corre en http://localhost:5173/ con hot reload; los cambios en código se reflejan automáticamente en el navegador.

Build de producción

npm run build

Genera la carpeta dist/ con todos los archivos listos para servir como sitio estático.

Para previsualizar el build localmente:

npm run preview

Actualizar dependencias

# Ver qué dependencias tienen versiones nuevas
npm outdated

# Actualizar dentro de los rangos de package.json
npm update

# Reconstruir después de actualizar
npm run build

Para actualizar una dependencia a una versión major nueva (por ejemplo, marked de 15.x a 16.x):

npm install marked@latest
npm run build

Actualizar JShell

Los artefactos de JShell están en public/jshell/. Para reconstruirlos desde cero (descarga Temurin JDK 17, extrae módulos, aplica parches para CheerpJ, y compila JShellBridge):

npm run update-jshell

Requiere Java 17+ instalado (para jmod, jar, javac).

Deploy

El deploy a GitHub Pages es automático. Cada push a main dispara un GitHub Action que:

1. Instala dependencias (npm ci)
2. Genera el build (npm run build)
3. Despliega dist/ a GitHub Pages

Para que funcione, en el repo de GitHub ir a Settings > Pages y en Source seleccionar GitHub Actions.

Estructura del proyecto

index.html                Punto de entrada (Vite entry point)
css/notebook.css          Estilos responsive mobile-first con dark/light mode
js/                       Lógica de la aplicación (ES modules)
  app.js                  Navbar, settings, shortcuts, read mode, autosave, ejemplos
  tab-manager.js          Múltiples notebooks en pestañas, barra tabs + menú acciones
  cell-manager.js         Ciclo de vida de celdas, selección, ejecución, mutaciones DOM
  cell-renderer.js        Creación del DOM para celdas code/markdown (Bootstrap cards)
  editor-setup.js         Factory de CodeMirror 6 (Java + Markdown syntax, keymaps, temas)
  notebook-model.js       Modelo de datos .ipynb (parse/serialize)
  jshell-proxy.js         Proxy a CheerpJ + JShellBridge (init, eval, reset, close)
  ipynb-io.js             Import/export .ipynb, drag-drop, autosave
src/                      Código fuente Java
  JShellBridge.java       Bridge multi-sesion entre JS y JShell (CheerpJ library mode)
  MhExecutionControl.java ExecutionControl custom (invoca do_it$ via MethodHandle
                          para que las excepciones no se pierdan en CheerpJ).
                          Sincronizado desde el repo "jshell"; ver el header del archivo.
  build.sh                Compila el bridge contra el jdk.jshell.jar parcheado.
public/                   Archivos estáticos (Vite los copia tal cual a dist/)
  jshell/                 JARs de JShell + clases compiladas (~5.6 MB)
  examples/               Notebooks de ejemplo (.ipynb)
package.json              Dependencias y scripts npm
vite.config.js            Configuración de Vite
update-jshell.mjs         Reconstruye los artefactos de JShell desde Temurin JDK 17
                          (descarga el JDK, extrae módulos, aplica parches CheerpJ,
                          inyecta MhExecutionControl en jdk.jshell.jar).
start.sh                  Script de inicio para Linux/macOS
start.bat                 Lanzador para Windows (cmd → PowerShell para cargar fnm/nvm)
start.ps1                 Lógica real del inicio en Windows, invocada por start.bat

Stack técnico

• Vite: build tool + dev server
• Bootstrap 5: framework CSS + componentes JS (navbar, tabs, cards, modals)
• Bootstrap Icons: íconos consistentes en toda la UI
• CodeMirror 6: editor de código con syntax highlighting Java y Markdown
• marked: renderizado de markdown
• KaTeX: renderizado de LaTeX en celdas markdown ($...$ inline, $$...$$ bloque)
• CheerpJ: JVM completa en WebAssembly (Java 17)
• JShell: REPL de Java 17 para evaluar código interactivamente