Skip to content

CLAUDE.md

Latest commit

 

History

History
55 lines (36 loc) · 5.19 KB

CLAUDE.md

File metadata and controls

55 lines (36 loc) · 5.19 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

A collection of standalone p5.js examples for teaching and learning, by Jon Froehlich and the Makeability Lab (UW). Categories span sound visualization, computer vision (ml5.js), games, generative art, Web Serial, animation, color, vectors, Perlin noise, and more.

Each example is a self-contained folder with its own index.html. There is no app-wide build step, bundler, or shared runtime — examples are independent and load p5.js (and other libs) from CDN.

Running and developing

  • Most examples: open the folder's index.html directly in a browser, or use VS Code Live Server.
  • Web Serial examples (WebSerial/): require a local web server (browsers block serial access from file://). Use Live Server. Requires Chrome/Edge/Opera. The Web Serial wrapper is Serial from the Makeability Lab JS library, loaded via CDN: https://cdn.jsdelivr.net/gh/makeabilitylab/js@main/dist/makelab.serial.iife.js.
  • Zero toolchain to run/develop examples: no npm, no build step, no npm install required to run or develop an example — just a browser (and Live Server for serial). Keep it that way. (The repo-root package.json and its Playwright/ffmpeg dev deps exist only for gallery preview generation — they are never on any example's load path. See scripts/README.md.)
  • IntelliSense: p5 type definitions are vendored in _p5types/ and wired up by the single root jsconfig.json, so VS Code autocomplete works offline with no install. Do not reintroduce @types/p5/node_modules for types, and do not add per-folder jsconfig.json files (a single root config covers the whole repo).

Adding a new example

  1. Create a folder under the right category, e.g. Sound/MyNewVis/.
  2. Add index.html (and optional sketch.js, css/style.css).
  3. Give the page a meaningful <title> — the gallery scrapes it (generic titles like "p5.js"/"index" are skipped, see extract_title_from_html in scripts/build_gallery.py).
  4. Commit and push to main; the gallery rebuilds automatically and a thumbnail preview is captured for the example. Optionally add a preview.json (skip/tune capture) or a hand-made screenshot.*/thumbnail.* — see scripts/README.md.

Templates/ holds starter scaffolds (Simple, Multi, Autogenerated) — copy one when starting a new sketch.

The gallery (auto-generated — do not hand-edit)

  • The repo-root index.html is generated by scripts/build_gallery.py, which walks the tree, finds every folder with an index.html, groups by category (top-level folder) and optional subcategory, and writes a self-contained page. Never edit root index.html by hand — it is overwritten on every build.
  • Thumbnails are auto-captured by scripts/capture_previews.mjs (Playwright + ffmpeg) into previews/<rel_path>.webp (animated) + .poster.png, committed to the repo. It content-hashes each example via previews/manifest.json and skips unchanged ones. build_gallery.py --list-json is its single source of truth for the example set, so the two never disagree. Full pipeline: scripts/README.md.
  • .github/workflows/build-gallery.yml runs both scripts on every push to main and commits index.html + previews/ back with [skip ci] (prevents an infinite loop). Published via GitHub Pages from main at root.
  • To regenerate locally: node scripts/capture_previews.mjs then python scripts/build_gallery.py (run from repo root).
  • Categories excluded from the gallery are configured in EXCLUDED_DIRS in the build script: _libraries, _p5types, .vscode, .github, scripts, node_modules, Arduino, Node, Sandbox, Templates.

Library / CDN conventions

CDN library versions are pinned, not floating (no @latest). Current pins: p5.js & p5.sound 1.11.13, ml5.js 0.12.2. When adding or editing examples, match these pins. Maintenance scripts in scripts/:

  • audit_libraries.py — scan repo for library import issues and pinning status.
  • fix_libraries.py — pin CDN versions, replace local lib refs with CDN, clean up local copies. Supports --dry-run.
  • migrate_serial_imports.py — migrate old _libraries/serial.js refs to the makeabilitylab/js CDN.

_libraries/ holds offline copies of libs (for local dev without internet); _p5types/ holds p5 type definitions. Neither is part of any example's normal load path — examples use CDN.

Conventions

  • HTML: 2-space indentation.
  • Vanilla JS only (no frameworks). p5.js global mode (setup()/draw()).
  • Web Serial examples follow the event-wiring pattern in WebSerial/Basic/SliderOutSuperBasic/ — instantiate new Serial(), register SerialEvents handlers, guard navigator.serial and wrap serial.connectAndOpen() in try/catch.

Related repositories