jtpio / p5-notebook

A Jupyter Notebook environment for p5.js kernels running in the browser, powered by JupyterLite 💡

p5-notebook

A minimal Jupyter Notebook UI for p5.js kernels.

p5-screencast-1.webm

Usage

✨ Try it in your browser! ✨

Features 🎁

Opens with Jupyter Notebook by default 📒

By default, the p5 notebook opens with the simpler notebook interface.

p5-screencast-1.webm

JupyterLab interface 🧪

The JupyterLab interface is still accessible via the View > Open in JupyterLab menu entry:

p5-screencast-2.webm

Live preview of HTML-based sketches ⚡

With the JupyterLab interface, .html files can be edited and rendered live with the built-in HTML viewer:

p5-screencast-3.webm

Support for themes 🌈

The p5 notebook includes the default JupyterLab Light and Dark themes, as well as p5.js branded light and dark themes:

p5-screencast-4.webm

Support for additional display languages 🌐

Just like with JupyterLab, the p5 notebook also supports additional display languages like French and Simplified Chinese:

p5-screencast-5.webm

JupyterLab and Notebook features 🎨

Most of the JupyterLab and Jupyter Notebook features are also available, such as switching to the Simple Interface and opening the command palette:

p5-screencast-6.webm

Real Time Collaboration

Coming soon!

Dev install

This repo includes a couple of additional plugins to tweak the Jupyter UI. To setup a local environment and be able to iterate on them, make sure Node.js is installed, then:

# install dependencies
pixi install

# Install package in development mode
pixi run develop

# Rebuild the extension Typescript source after making changes
pixi run build

Related projects

• nb5.js, a notebook for p5js sketches (proof of concept): https://github.com/aparrish/nb5js-proof-of-concept

• p5.js Jupyter Widget: https://github.com/jtpio/ipyp5

• [archived / demo] p5.js in the Classic Jupyter Notebook with Jupyter Widgets: https://github.com/jtpio/p5-jupyter-notebook

• Jupyter Kernels, right inside JupyterLab: https://github.com/deathbeds/jyve

• JupyterLite has:

  • Python kernel backed by Pyodide running in a Web Worker
    • Initial support for interactive visualization libraries such as altair, bqplot, ipywidgets, matplotlib, and plotly
  • JavaScript and P5.js kernels running in an IFrame

  https://github.com/jupyterlite/jupyterlite

p5-notebook's Issues

Add a toolbar button to rename the notebook

There could be a button to the left of the save button in the notebook toolbar, to open a dialog and rename the notebook.

Add a pyp5js with pyodide kernel

It would be nice to be able to switch between:

• a pure p5.js JavaScript kernel
• a Python kernel that exposes the p5 API, using pyp5js with pyodide, and everything still running in the browser

This would also be useful to prepare the ground for a tighter integration with Jupyter Widgets in a more traditional setup: jtpio/ipyp5#4

Add p5 branded theme

With some pink-ish colors.

And in jupyter-lite.json:

• Enable themed scrollbars by default
• Enable that theme by default

Add a SplashScreen

For now toggling the theme doesn't show a splash screen.

In some way this is good because there is no animation and everything is snappy.

But we might want to experiment with a custom "p5 branded" splash screen. That would involve writing a plugin similar to this one:

https://github.com/jupyterlab/jupyterlab/blob/a8d49aaa89709edba0d0ae49cc8ad7f3582a949b/packages/apputils-extension/src/index.ts#L136-L244

Download the notebook as an .ipynb file

There should be a way to download the notebook as an ipynb file.

Either as a notebook toolbar button, or by adding a minimal menu at the very top.

Implement missing messages

There are still a couple of message missing in the kernel implementation.

Implement streams

This will most likely involve patching console.log and console.error, as well as gracefully handling exceptions.

Rebuild with JupyterLite

Once the JupyterLite tooling is ready:

• convenient jupyterlite Python package, or JS equivalent to get the main app assets
• tooling to support serverlite extensions to add the p5 related kernels

We should "reboot" this repo, which might end up being a light monorepo with just a couple of packages for the kernel (the rest being reuse from JupyterLite).

For the UI, we can also default to RetroLab.

Open from URL

Sketches could be imported from other notebooks by pasting a URL in an input field.

Open the sketch in a split view

Just like JupyterLab make it possible to open to have 2 documents side by side, it would be useful to open the sketch in a split view (left or right), so the notebook can still be edited and scrolled.

This could be achieved by adding a button to the notebook toolbar.

Roadmap

Here are a couple of items for the p5 notebook roadmap.

Some of them actually apply to a wider scope than just p5, and would define the building blocks for more generic in-browser jupyter kernels.

The idea is to start with the special case of the p5 notebook with multiple notebooks, and make it more generic afterwards.

• Add a pyp5js kernel backed by pyodide: #52
• Improve kernel management (#7)
• Define a public interface to register kernels
• Save notebooks to local storage: #20
• Add a simple file browser to create, save and re-open existing notebooks
• Consolidate the jupyterlab server to it's functional for most of the use cases (but it doesn't have to be feature complete)
• Make the jupyterlab server pluggable using the same lab / lumino plugin system:
  • So users could replace some of the plugins, for example the contents manager
  • For example instead of writing to local storage this could be talking to external services using API calls
• Split up the components and switch to a monorepo structure
• Move some of the components to a separate repo
• p5 notebook should only be a distribution:
  • depending on the jupyterlab server in the browser
  • shipping with a predefined set of kernels
  • with its own minimal notebook UI (logo + p5 touch)
• Add a splash screen: #23
• Publish to npm: #27

Update Readme

Update the main README to serve as documentation and:

• showcase features
• where the project fits compared to the p5js web editor and the Jupyter ecosystem
• document how to install on a custom lite deployment
• lab vs retro

Add a top area

A top area similar to the classic notebook, but trimmed down to the minimal, would be useful to:

• show the p5 logo
• manage notebooks (download, upload, create new) and load examples.
• show the help
• add extra widgets such as the theme-toggle topbar plugin
• manage multiple notebooks (if not too complicated)

Replace raw localStorage by StateDB + DataConnector

Instead of using localStoragedirectly, we could instead make use of a StateDB with a DataConnector that would use localStorage as storage.

This would make the implementation more generic, and could be reused to store other type of content.

Split frontend parts into plugins

The "frontend" should be split into plugins (JupyterFrontEndPlugin[]).

The app would load all the predefined plugins at start-up using app.registerPluginModules(plugins);

This leaves the door open for adding plugins from existing third-party JupyterLab extensions.

Implement a Web Worker kernel

It would be interesting to implement a Web Worker kernel, just for fun.

Also the users of the p5 notebook could switch between a pure JS kernel and a p5.js kernel using the kernel selection dialog from the notebook toolbar.

Use postMessage to send messages to the IFrame

Instead of doing raw eval on the IFrame window directly, postMessage could be used to push more logic to the IFrame context.

Add an HTML example

Using the htmlviewer-extension added in jupyterlite/jupyterlite#365

We need a new jupyterlite release first.

Handle kernel restarts

The IFrame should be recreated upon restart.

Similar project: Starboard

Hi Jeremy,

I came across this repo when exploring the rabbit hole that is alternative notebook projects. I'm building a notebook system, not based on Jupyter, that runs entirely in the browser by design and is entirely static (like p5-notebook). I recreated the P5 example notebook here, here it is entirely statically which you could embed anywhere.

One cool thing is that there is no one 'kernel' and no 'magic' (it's all just JS), so you can really mix different languages. Also you can "build the ship as you sail", similar to Jyve. You can even write P5 code in Python through pyodide if you want :). The homepage has some more details, it's open source here.

Curious to hear your thoughts and happy to bounce ideas!

Publish to npm

The package should be published to npm, so it can used on a local machine too.

It can also be made compatible with npx, so that running npx p5-notebook (or npx p5nb) starts a server in the local directory and open a new browser tab. It should also serve other type of content such as images.

Save notebook to local storage

The example notebook should be put in the menu: "File -> Load Example".

The notebooks could be stored in the browser localStorage, so they are not lost after a page refreshed.

Add support for instance mode

It would be great to have support for instance mode:

https://p5js.org/examples/instance-mode-instantiation.html

The sketch could then be displayed by evaluating it.

Handle multiple notebooks

Ideally there should be a way to have multiple notebooks on the page (each with a separate kernel), and be able to switch between them easily, while keeping the interface as simple as possible.

Use webpack CopyPlugin to copy resources

Consider switching to the CopyPlugin:

https://webpack.js.org/plugins/copy-webpack-plugin/

Instead of manually copying directories:

p5-notebook/webpack.config.js

Line 8 in 3069f5b

fs.copySync(resources, target);

Add a Help menu

With the following entries:

• about + link to this repo
• link to the p5.js reference
• link to jupyter.org?
• show shortcuts

Add a q5 kernel

Once adding new kernels is easier, we should consider adding q5 to the p5 notebook distribution.

A small and fast alternative (experimental) implementation of p5.js

https://github.com/LingDong-/q5xjs