Setup

This repo uses a conductor.json setup script (make install) that runs automatically when a Conductor workspace is created. It installs all dependencies so the environment is ready to use immediately.

Agents

wigglystuff ships a small roster of AnyWidget "agents" that surface different input modalities (sliders, speech, paint, etc.) across notebook runtimes. This page is a quick lookup so you can see what exists and which traitlets each agent syncs back to Python.

Quick reference

Patterns to remember

Visual approval comes before verification

• For new widgets and visual or interaction changes, stop once the implementation and demo are ready for inspection. Give the user a concrete way to open the widget, then wait for explicit visual approval before running test suites, requesting code review, updating galleries/docs, committing, pushing, or starting branch-finishing workflows. The user may want another design pass.
• During visual iteration, do not repeatedly run automated checks after CSS, SVG, layout, or styling tweaks. Make the change and return it for inspection.
• After visual approval, run the smallest focused checks once. Run the full repository suite only when preparing to ship/merge or when shared infrastructure changed.
• Keep widget unit tests compact: cover each public behavior once, group repetitive validation cases in one test, and avoid parameter matrices that multiply test count without adding distinct behavioral coverage.
• All agents inherit from anywidget.AnyWidget, so widget.observe(handler) remains the standard way to react to state changes.
• Constructors tend to validate bounds, lengths, or choice counts; let the raised ValueError/TraitError guide you instead of duplicating the logic.
• Several widgets expose helper methods (e.g., Paint.get_pil(), EdgeDraw.get_adjacency_matrix())—lean on those rather than re-implementing conversions.
• Check wigglystuff/__init__.py for the names that are re-exported at the package root so you can keep imports consistent.
• numpy and pillow are optional dependencies. They are listed under [project.optional-dependencies] in pyproject.toml, not in the core dependencies. Widgets that need numpy or pillow must import them inside the method or function that uses them (never at module top-level). This keeps import wigglystuff and widgets that don't need these libraries working without them installed. Install with pip install wigglystuff[all] to get both, or wigglystuff[numpy] / wigglystuff[pillow] individually.
• The repo standardizes on uv for Python workflows (uv pip install -e . etc.) and the standard library's pathlib for filesystem paths—mirror those choices in new agents to keep the codebase consistent.
• When styling widgets, support both light and dark themes by defining component-specific CSS variables (see Matrix/SortableList). Scope your defaults to the widget root, mark color-scheme: light dark, and provide overrides that respond to .dark, .dark-theme, or [data-theme="dark"] ancestors so notebook-level theme toggles work instantly.
• When adding a new widget, remember to update the docs gallery (docs/index.md), the README gallery (readme.md), the LLM context file (docs/llms.txt), and the changelog (CHANGELOG.md). Add a screenshot to docs/assets/gallery/ and reference it from the gallery locations to keep them in sync. Screenshots are stored as .webp — if you only have a PNG, drop it in and run uv run python scripts/png_to_webp.py to convert and clean up.
• Every link to MoLab (molab.marimo.io) must carry ?utm_source=wigglystuff so outbound traffic is attributable in analytics. This applies to the gallery links in README.md and docs/index.md and any MoLab reference in docs/llms.txt. When adding a new widget, append the param to its molab demo links (e.g. .../demos/<name>.py/wasm?utm_source=wigglystuff).
• New or changed features that haven't been released yet go under the ## [Unreleased] section at the top of CHANGELOG.md. That section gets renamed to a versioned heading (e.g., ## [0.2.37]) only at release time.
• At release time, also bump the wigglystuff==X.Y.Z pin in the script header of every demo notebook that exercises an unreleased feature. The demos/*.py files use PEP 723 # /// script blocks that pin a published version — if a demo uses APIs only present in the new release, leaving the old pin means uv run demos/<name>.py (and anyone who downloads the demo) will get the old wigglystuff and the feature will be missing. After bumping pyproject.toml, grep demos/ for the previous version and update the pins on any demo touched in the release.
• Each widget has a demo marimo notebook in the demos/ folder (e.g., demos/colorpicker.py). When adding a new widget, create a corresponding demo notebook. Run demos with marimo edit demos/<widget>.py.
• After visual approval, smoke-test new or modified widget code with uv run python -c "..." to instantiate the widget, exercise traitlet changes, and check edge cases (built-ins, empty inputs, toggles).
• After visual approval, run uv run marimo check demos/<notebook>.py after editing a demo notebook to verify it parses correctly and has no cell dependency issues. which only validates structure.
• Dumber is better. Prefer obvious, direct code over clever abstractions—someone new to the project should be able to read the code top-to-bottom and grok it without needing to look up framework magic or trace through indirection.
• Do not modify package-lock.json unless intentionally updating JS dependencies. If it shows up in git diff, revert it with git checkout package-lock.json.
• Docs are built with zensical, not mkdocs. The config lives in zensical.toml; build with make docs and preview with make docs-serve (which builds, then serves site/ via python -m http.server). Packages like mkdocstrings are zensical plugins — their presence is not evidence that this is an mkdocs project.
• When planning a new widget, always present the proposed Python API (constructor, traitlets, helper methods) during plan review so the user can sign off on the interface before implementation.