Roclet

A reactive notebook for Roc, right in your browser.

Change a value and watch the rest of your notebook update. Put the explanation next to the code, add an equation, and share the result as a readable HTML report. Roclet runs Roc locally through WebAssembly—and keeps working offline.

• Reactive by default. Cells follow their dependencies, not their position on the page.
• Files you can read. Save notebooks as Roc or Markdown. Export runnable Roc scripts.
• Room to think. A quiet editor with keyboard navigation, multiple cursors, and collapsible source.
• More than plain text. Markdown, math, tables, images, interactive Plotly charts, and inline dbg output.
• Bring your data. Attach local files as exact copies, import UTF-8 text or raw bytes, and keep them in portable bundles.
• Take your work with you. Download a notebook, share a portable bundle, or export a self-contained report.

Try it

Open Roclet — no installation needed. Prefer a local copy? Install the optional server.

Try the Rich Outputs and Widgets demo, change width, and see what happens. The installation guide covers offline use and running locally.

Or explore the little demos: a simple reactive calculation, a coding puzzle with checks and hints, a meeting scheduler using roc-time, and interactive charts with Plume. The CSV attachments demo uses roc-parser to turn an attached sales file into a report. Replace the CSV through File → Attachments to try your own data.

In a code cell, definitions are shared across the notebook. The last expression is the result to display:

radius = 3
pi = 3.141592653589793
pi * radius * radius

Press Cmd/Ctrl+Enter to run a cell. Esc selects the cell; Enter edits it. With Auto-run enabled, changes update dependent results as you type. Each notebook's title, Auto-run and Run all sit at its top; while it is saving, running or waiting for a package, Stop takes Run all's place without moving the bar. Its status and save state sit in a bar at its bottom. Roclet shows a loading screen until the notebook and its prose are ready; evaluation and package downloads start only then. File → Open recent… lists the drafts in this browser; Help → Keyboard shortcuts (or ? with a cell selected) lists the keys.

Choose Insert → Widget, Chart, Rich output, or Code snippet for searchable, ready-to-edit examples with output previews. + Insert… between cells opens the same picker at that position. Inserting an example adds its packages and imports automatically; one Undo removes the whole insertion. Random examples use an explicit seed so results stay repeatable as the notebook recomputes.

To work with two notebooks at once, choose View → Open side by side…. Each notebook gets its own column and its own compiler, so running or stopping one never disturbs the other; menu commands act on the notebook you last clicked, named at the top of each menu. Below 900px wide the two notebooks become tabs. A notebook can be open in only one column at a time; Roclet offers to switch to it or to open an independent copy instead. If another tab changed a draft, closing or switching away from it offers a download or to continue without saving. View → Show engine details adds the last run's worker time, evaluated and reused results, and memory to each status bar.

Sliders and numeric widgets update as evaluation can keep up, retaining the latest pending value. Charts keep their zoom, pan and resized height. During a drag, intermediate results are marked as updating; only current results can be exported. The status timing includes scheduling, saving and output rendering; engine details show worker time separately. Source typing still waits briefly for you to settle.

Drafts are saved in your browser. Save can write a local file, while Download a copy keeps a separate copy.

For a local project, run roclet serve ./my-project (or pass a notebook path). Roclet opens in your browser, saves directly to disk, loads local modules, and downloads packages automatically. See the local project guide for building or running the downloaded distribution.

Open a GitHub Gist

Choose File → Open GitHub Gist…, paste a Gist URL or ID, and open a copy. You can also share a direct Roclet link:

https://ageron.github.io/roclet/web/edit.html?gist=GIST_ID

Name the main notebook notebook.roc or notebook.md (also recognized: Main.roc and main.roc). A single .roc or .md file is selected automatically. For other names or multiple notebooks, add &gistFile=notes.md to the link or enter the notebook filename in the dialog.

Try the Gist garden example: a small notebook declares garden: "./garden.roc" in its app header and imports garden.Garden. The package entry, exposed module, internal helper, and planting notes all come from the same revision-pinned Gist. See the demo sources.

Other .roc files become Project files, so import Geometry can load a Geometry.roc from the same Gist. Other text files become Attachments at their Gist filenames, for example import "sales.csv" as csv : Str. Gists use flat filenames; use a local project or Roclet bundle for directory trees or binary data.

To pin a version, set gist to a full Gist revision URL (URL-encode it when building a link). Otherwise Roclet loads the latest version each time the link is opened. Each import creates an independent browser draft and waits for Run. Edits stay in your browser; download a copy or bundle to keep or share them. Saving back to GitHub is not supported.

Loading needs an internet connection and is subject to GitHub's unauthenticated API rate limits. Notebook and project size limits still apply. Roclet rejects incomplete API responses, including files GitHub marks as truncated, instead of opening partial code. Use smaller files or a bundle if this happens.

Early days

Roclet is an experimental alpha. Only Chrome has been tested. Other browsers may work, but haven't been verified yet. Native builds have been tested on Linux x86_64 and macOS with Apple Silicon.

Roclet uses a pinned development version of Roc. If something breaks, please open an issue with a small notebook that reproduces it, your browser version, and what you expected.

Build it yourself

You'll need Zig 0.17.0, Git, tar, and a checkout of the Roc compiler. There is no Node.js or npm requirement.

sh tools/prepare-compiler.sh /path/to/roc
zig build
zig build serve

Open http://127.0.0.1:4173/web/edit.html. The installation guide covers the compiler checkout, offline use, downloads, and sharing. The design describes where Roclet is heading.

Add supporting modules through File → Project files. Roc package declarations use the notebook's normal app header. Browser builds cache compiler artifacts and verified packages locally; warm edits reuse them without downloading dependencies again. A static package mirror supplies every bundled demo dependency and a curated collection of common libraries automatically, without an external download service. For packages outside that collection, the default public fetcher downloads GitHub release archives automatically. If automatic downloading fails, Roclet offers a download link and lets you load the bundle from your computer, verifying its hash before use. This works on a completely static host. Portable Roclet bundles include your attached project sources.

Choose File → Attachments to copy data files into a notebook. Each attachment has a stable relative path; Replace file keeps that path, and Remove can be undone. Import UTF-8 text with import "data/sales.csv" as csv : Str, or use List(U8) for exact binary bytes. Browser drafts retain the files. Download a Roclet bundle to include them; a .roc or .md source download contains only code and prose. See attachments.

Architecture

• Runtime overview: browser execution, storage, local server, packages, and the optional native runner.
• Inside the engine: document preparation, reactive evaluation, the Roc compiler, and the interpreter.
• Build and distribution: engine caches, independent Display assets, CI, website deployment, and server releases.

The local server serves files and downloads packages; notebooks still execute in the browser's WASM engine. The native runner uses the same Zig core in a separate executable. Display modules and their release URL are runtime assets, so their updates do not require recompiling either engine.

Editable Graphviz sources and PNG copies are alongside the SVG diagrams in docs/architecture/. To regenerate with Graphviz installed:

for name in runtime engine build; do
  dot -Tsvg "docs/architecture/$name.dot" -o "docs/architecture/$name.svg"
  dot -Tpng "docs/architecture/$name.dot" -o "docs/architecture/$name.png"
done

License

Universal Permissive License 1.0, the same license as Roc. Vendored dependencies retain their own licenses.