If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/nannou-org/nannou shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Missing license — unclear to depend on

• Last commit 1w ago
• 19 active contributors
• Distributed ownership (top contributor 41% of recent commits)
• CI configured
• Tests present
• ⚠ No license — legally unclear to depend on

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live nannou-org/nannou repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/nannou-org/nannou.

What it runs against: a local clone of nannou-org/nannou — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in nannou-org/nannou | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 39 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of nannou-org/nannou. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/nannou-org/nannou.git
#   cd nannou
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of nannou-org/nannou and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "nannou-org/nannou(\\.git)?\\b" \\
  && ok "origin remote is nannou-org/nannou" \\
  || miss "origin remote is not nannou-org/nannou (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "nannou/Cargo.toml" \\
  && ok "nannou/Cargo.toml" \\
  || miss "missing critical file: nannou/Cargo.toml"
test -f "nannou_wgpu/Cargo.toml" \\
  && ok "nannou_wgpu/Cargo.toml" \\
  || miss "missing critical file: nannou_wgpu/Cargo.toml"
test -f "nannou_core/Cargo.toml" \\
  && ok "nannou_core/Cargo.toml" \\
  || miss "missing critical file: nannou_core/Cargo.toml"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 39 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~9d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/nannou-org/nannou"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Nannou is an open-source creative coding framework for Rust that provides artists and developers with a Processing/OpenFrameworks-like toolkit for generative art, interactive visualizations, and creative installations. It abstracts over wgpu for GPU rendering, includes built-in drawing primitives, audio processing via nannou_audio, and UI support through nannou_egui, enabling rapid prototyping from sketches to production installations. Monorepo structure: core nannou crate wraps nannou_core and nannou_wgpu (GPU abstraction), with specialized modules for audio (nannou_audio), UI (nannou_egui), mesh (nannou_mesh), OSC (nannou_osc), and laser output (nannou_laser). Examples live in examples/ directory with asset files in assets/ (fonts, sample images, HRIR). Build tooling via scripts/ for versioning and example runners.

Artists, creative technologists, and Rust developers building generative art, interactive installations, data visualizations, and audio-reactive graphics who want type-safe, performant creative code without the cognitive overhead of low-level graphics APIs. Contributors are typically creative coders familiar with Processing/Cinder who want Rust's safety guarantees.

Actively developed but still in early-stage evolution (repo indicates 'still early days and there is a lot of work to be done'). Has substantial codebase (1.7M lines of Rust), organized CI via .github/workflows/nannou.yml, and comprehensive guide at guide.nannou.cc, but version management script (scripts/set_version) and breaking change warnings suggest API instability. Production-ready for stable use cases but expect breaking changes between releases.

Monorepo complexity with 17 workspace members (nannou_audio, nannou_egui, nannou_wgpu, etc.) introduces dependency coupling risk; wgpu is itself in active development. No visible open issue count provided, but 'early days' language suggests incomplete feature coverage. Platform-specific dependencies (fonts in assets/, HRIR audio files) may cause setup friction. Single organization maintainer model typical for creative frameworks; ecosystem smaller than Processing but growing.

Workspace actively maintains multiple crate versions in parallel and supports wgpu renderer updates (v0.10+ indicated in Cargo.toml resolver comment). Guide documentation is continuously maintained at guide.nannou.cc with community tutorials. Recent work includes egui integration (nannou_egui_demo_app) and ISF plugin support (nannou_isf). Generative design examples and nature of code implementations suggest educational focus expansion.

git clone https://github.com/nannou-org/nannou.git
cd nannou
cargo build
cargo run --example draw_polygon --release

Note: Requires Rust toolchain (install via rustup per guide.nannou.cc/getting_started/installing_rust.html) and platform-specific setup documented at guide.nannou.cc/getting_started/platform-specific_setup.html.

Daily commands:

cargo run --example <example_name> --release

Examples reference specific example files in examples/ (e.g., draw_polygon.rs, simple_ui.rs). Development: cargo build for debug, cargo build --release for optimized builds. Consult guide.nannou.cc/getting_started/running_examples.html for specific example documentation.

• Cargo.toml — Workspace root defining all member crates (nannou, nannou_core, nannou_wgpu, nannou_audio, etc.) and resolver settings critical for dependency resolution.
• nannou/Cargo.toml — Main framework crate manifest specifying core dependencies (wgpu, winit, lyon) and feature flags that drive rendering and platform support.
• nannou_wgpu/Cargo.toml — GPU backend crate providing WebGPU abstraction layer; essential for understanding rendering pipeline architecture.
• nannou_core/Cargo.toml — Core math, color, and utility types shared across all nannou crates; foundational data structures.
• README.md — Project overview and philosophy; clarifies nannou's positioning relative to Processing/OpenFrameworks and its creative-coding goals.
• CONTRIBUTING.md — Contributor guidelines, development workflow, and coding standards essential for PRs and community contributions.
• examples/README.md — Example organization and execution instructions; guides new contributors on running and extending example sketches.

Add a new drawing primitive or shape

1. Define the shape type and builder in nannou_core math module (e.g., struct for vertices, bounds, properties) (nannou_core/Cargo.toml)
2. Implement rendering backend in nannou_wgpu with shader bindings and vertex/index buffer setup (nannou_wgpu/Cargo.toml)
3. Export public API through nannou::draw module with fluent builder pattern (nannou/Cargo.toml)
4. Add example sketch demonstrating the new primitive in examples/ directory (examples/README.md)

Add audio processing or input handling

1. Define audio types and trait interfaces in nannou_audio module (nannou_audio/Cargo.toml)
2. Integrate CPAL host API and manage audio streams via the App model (nannou/Cargo.toml)
3. Expose callbacks (update, audio_input, audio_output) in main app event loop (nannou/Cargo.toml)
4. Create example in examples/audio/ demonstrating the new capability (examples/audio/feedback.rs)

Add an interactive GUI component or tool

1. Build on nannou_egui crate for immediate-mode rendering of widgets (nannou_egui/Cargo.toml)
2. Integrate egui painter and input handling into the nannou event system (nannou/Cargo.toml)
3. Extend nannou_egui_demo_app with new widget examples and state management patterns (nannou_egui_demo_app/Cargo.toml)
4. Document widget usage in guide or comment-driven examples (examples/README.md)

Add support for a new I/O protocol or external service

1. Create new subcrate (e.g., nannou_xyz) or extend nannou_osc with protocol definitions (nannou_osc/Cargo.toml)
2. Implement networking, parsing, and serialization using appropriate Rust libraries (nannou_osc/Cargo.toml)
3. Expose high-level API through nannou app hooks (e.g., event streams, callbacks) (nannou/Cargo.toml)
4. Add example demonstrating the new I/O capability with real-world use case (examples/README.md)

• Rust — Memory safety without GC, zero-cost abstractions, and strong performance for real-time creative applications; aligns with Processing/OpenFrameworks design goals.
• WebGPU (wgpu) — Cross-platform GPU abstraction (DX12, Vulkan, Metal); enables portable, modern GPU compute with strong type safety compared to raw OpenGL.
• winit — Lightweight, cross-platform window and event handling; decoupled from rendering, allowing flexible integration with different GPU backends.
• lyon — CPU-side 2D path tessellation; enables vector graphics without depending on GPU-specific rasterization, improving portability.
• CPAL — Platform-agnostic audio I/O (Windows/macOS/Linux); essential for real-time audio input/output in creative sketches.
• egui — Immediate-mode GUI framework compatible with WebGPU; reduces boilerplate for interactive tools and parameter panels.

• Monorepo with many crates (nannou, nannou_core, nannou_wgpu, nannou_audio, etc.)

  • Why: Allows fine-grained dependency management and optional features (audio, GUI, lasers) without bloating a single large crate.
  • Consequence: Increased complexity in workspace management and potential version coordination overhead; mitigated by workspace resolver v2.

• CPU-side tessellation (lyon) for 2D primitives instead of pure GPU rendering

  • Why: Simplifies shader code, improves compatibility, and gives precise control over vertex generation; CPU cost is negligible for typical sketches.
  • Consequence: Large batches of complex shapes may incur CPU overhead; not ideal for procedural GPU-native fractals, but acceptable trade-off for ease of use.

• Fluent builder API for drawing (e.g., draw.rect().x_y(0, 0).w_h(100, 100)) instead of functional composition

  • Why: More intuitive and readable for creative coders familiar with Processing style; reduces cognitive load.
  • Consequence: Builder state is ephemeral (consumed at frame boundary); less composable for reusable drawing functions, but simpler mental model.

• Audio via CPAL + user-provided callbacks rather than a built-in mixer/DSP

  • Why: Minimizes dependencies and gives artists full control over audio pipeline; separate nannou_audio crate can be extended.
  • Consequence: Artists must implement their own mixing and effects; provides freedom but steeper learning curve for audio beginners.

• Resolver v2 for workspace to handle wgpu v0.10 transitive dependencies

  • Why: Prevents feature resolution conflicts between crates with different wgpu version requirements.
  • Consequence: Requires

Platform-specific setup required: guide.nannou.cc/getting_started/platform-specific_setup.html indicates non-standard platform dependencies (likely audio/graphics drivers). Workspace resolver v2 mandatory: Cargo.toml comment warns wgpu v0.10 requires resolver = '2'; older projects may conflict. Asset paths: Examples reference assets/ directory with absolute-like paths; running from different directories may fail image/font loading. Font licensing: NotoSans fonts in assets/fonts/NotoSans/LICENSE-2.0.txt must be respected if distributing. HRIR audio file: assets/hrir/IRC_1002_C.bin is binary data; ensure it's not corrupted in clones. Early API stability: CHANGELOG.md not fully visible but 'early days' language suggests no semver guarantees; breaking changes between releases likely.

• Immediate-mode GUI (IMGUI) — Nannou uses immediate-mode UI (egui) rather than retained-mode, meaning every frame rebuilds UI state; essential mental model for interactive sketches without traditional event handlers
• GPU abstraction via wgpu — Nannou hides wgpu complexity via high-level draw API; understanding wgpu's compute pipelines and shader binding model helps debug graphics performance
• Cross-platform shader compilation (GLSL → SPIR-V → native) — Nannou supports both GLSL and WGSL shaders compiled to platform-native formats; shader portability across Windows/Mac/Linux/Web requires understanding this pipeline
• HRIR (Head-Related Impulse Response) for 3D audio — Assets include IRC_1002_C.bin HRIR data; nannou_audio uses HRIRs for spatial audio rendering in installations, a domain-specific audio processing technique
• OSC (Open Sound Control) protocol — Nannou_osc crate supports OSC for networked creative systems (common in installations); critical for multi-machine installations or DMX-like control
• Generative design and creative coding patterns — Generative_design/ directory and nature_of_code/ examples teach algorithmic art principles; understanding these patterns (noise, L-systems, genetic algorithms) is the domain language
• Workspace-based monorepo dependency management — 17 workspace members (nannou_audio, nannou_wgpu, nannou_laser, etc.) with shared versioning; Rust workspace resolver v2 is mandatory; breaking changes propagate across all members

• processing/processing — Direct inspiration for nannou's API design; Processing is the reference creative coding framework that nannou aims to replicate in Rust
• openframeworks/openFrameworks — Another direct inspiration mentioned in README; provides C++ creative coding patterns that informed nannou's architecture
• cinder/Cinder — Third inspiration source mentioned in README; C++ framework establishing UI/graphics abstractions nannou adapted for Rust
• gfx-rs/wgpu — Direct dependency: nannou_wgpu wraps wgpu for GPU compute; understanding wgpu internals necessary for graphics work
• emilk/egui — Immediate-mode UI library integrated via nannou_egui; required for building interactive UI on top of nannou sketches

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for nannou_audio module

The workspace includes a dedicated nannou_audio crate but there's no visible test directory structure in the file listing. Audio processing is critical for creative coding applications, and integration tests would ensure audio I/O, effects chains, and HRIR-based spatial audio (assets/hrir/IRC_1002_C.bin exists) work correctly across platforms. This directly supports the framework's goal of reliability.

• [ ] Create tests/ directory in nannou_audio/ with integration test structure
• [ ] Add tests for audio input/output device enumeration and selection
• [ ] Add tests for HRIR loading and spatial audio processing using the existing IRC_1002_C.bin asset
• [ ] Document test setup in nannou_audio/README.md for platform-specific audio backend requirements

Create platform-specific CI workflows for wgpu rendering validation

The .github/workflows/nannou.yml exists but likely doesn't have platform-specific GPU rendering tests. Given nannou_wgpu is a core workspace member and nannou targets multiple platforms (Windows/Mac/Linux), adding separate GitHub Actions workflows that test rendering on each OS with different GPU backends would catch platform-specific regressions. The existing asset images (assets/images/generative_examples/) could be used for visual regression testing.

• [ ] Extend .github/workflows/nannou.yml to add matrix builds for ubuntu-latest, macos-latest, windows-latest
• [ ] Add wgpu backend validation steps (Vulkan on Linux, Metal on macOS, DirectX on Windows)
• [ ] Create a new workflow file .github/workflows/rendering-tests.yml for GPU-specific tests
• [ ] Document GPU requirements and test setup in CONTRIBUTING.md

Add missing examples documentation and index for nannou_isf and nannou_laser

The workspace includes specialized modules (nannou_isf for shader composition, nannou_laser for laser graphics) with existing test assets (assets/isf/Test-*.fs files), but there's no discoverable documentation linking their examples to the main guide. New contributors cannot easily understand these subsystems. Creating curated example galleries with README files would improve onboarding and showcase framework capabilities.

• [ ] Create examples/isf_showcase/ directory with 3-4 annotated ISF composition examples using assets/isf/Test-*.fs files
• [ ] Create examples/laser_graphics/ directory with basic laser output and animation examples
• [ ] Add README.md files to both example directories explaining use cases and ISF/laser concepts
• [ ] Update guide/book_tests/ or main README.md with links to these example categories

• Add WGSL shader examples to match the 953KB of existing GLSL examples; currently only 7.9KB WGSL in repo, suggesting incomplete coverage of wgpu's native shader language
• Implement doctest coverage for nannou_core drawing primitives (no test files visible in file list); add passing examples in rustdoc for draw::rect(), draw::circle(), etc.
• Extend guide/book_tests/ with platform-specific setup validation scripts; currently guide links to platform setup but no automated test coverage exists for confirming dependencies (audio libs, graphics drivers) are installed

The Nannou creative coding framework demonstrates a reasonable baseline security posture as an open-source project. Primary concerns are: (1) lack of explicit security disclosure policy, (2) multiple workspace members without clear security boundaries, (3) binary assets without integrity verification, and (4) potential for dependency confusion attacks due to workspace complexity. The codebase does not exhibit obvious injection vulnerabilities, hardcoded secrets, or exposed credentials based on visible structure. No Docker configuration was provided for assessment. Recommendations focus on enhancing dependency management, implementing asset verification, and establishing clear security governance as the project scales.

• Medium · Workspace Resolver Version 2 Without Lock File Verification — Cargo.toml (resolver = "2" declaration). The Cargo.toml uses workspace resolver v2 without explicit dependency pinning strategy documented. While Cargo.lock exists, the presence of multiple workspace members increases the attack surface for dependency confusion or transitive dependency vulnerabilities. Fix: Ensure Cargo.lock is committed and verified in CI/CD. Implement dependency auditing with 'cargo-audit' in the CI pipeline. Review and pin critical transitive dependencies explicitly.
• Medium · Multiple Workspace Members Without Clear Dependency Boundaries — Cargo.toml (workspace members definition). The workspace contains 16 members including audio, graphics, OSC, laser, and ISF modules. Without visible access control or security boundaries between modules, a compromise in one module could affect others. Graphics rendering (wgpu) and audio processing are particularly sensitive. Fix: Implement feature gates to isolate modules. Document and enforce dependency policies between crates. Consider separating high-risk modules (audio, graphics, network) into distinct security zones with clear API contracts.
• Low · No Explicit Security Policy Documentation — Root directory (missing SECURITY.md). The repository lacks a SECURITY.md file for responsible disclosure of vulnerabilities. Only CODE_OF_CONDUCT.md and CONTRIBUTING.md are visible. Fix: Create a SECURITY.md file with vulnerability disclosure procedures, supported versions, and security contact information. Follow best practices from https://securitymd.org/.
• Low · Binary Asset Files Without Integrity Verification — assets/ directory (fonts, images, sounds, hrir, isf files). Multiple binary files (fonts, images, audio, HRIR data) are included in assets/ directory without visible checksums or integrity verification mechanisms. These could be vectors for supply chain attacks. Fix: Implement file integrity verification using SRI (Subresource Integrity) or cryptographic hashes. Document the source and verification status of all binary assets. Consider separating runtime assets from the repository.
• Low · GitHub Workflows Without Explicit Permissions Configuration — .github/workflows/nannou.yml. CI/CD workflow file (.github/workflows/nannou.yml) is visible but permissions configuration cannot be assessed from provided context. Default GitHub Actions permissions can be overly permissive. Fix: Explicitly define 'permissions' block in workflow files with principle of least privilege. Use 'contents: read' by default and only grant write permissions when necessary. Audit workflow triggers for untrusted input.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.