@devaloop/devalang 0.0.1-beta.3 → 0.1.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Devaloop Labs
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell    
-copies of the Software, and to permit persons to whom the Software is        
-furnished to do so, subject to the following conditions:                     
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.                              
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR   
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,     
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER       
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2025 Devaloop Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell    
+copies of the Software, and to permit persons to whom the Software is        
+furnished to do so, subject to the following conditions:                     
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.                              
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR   
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,     
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER       
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

package/README.md

@@ -1,221 +1,251 @@
-<div align="center">
-    <img src="https://devalang.com/images/devalang-logo-min.png" alt="Devalang Logo" width="100" />
-</div>
-
-![Rust](https://img.shields.io/badge/Made%20with-Rust-orange?logo=rust)
-![TypeScript](https://img.shields.io/badge/Built%20with-TypeScript-blue?logo=typescript)
-![Node.js](https://img.shields.io/badge/Node.js-18%2B-brightgreen?logo=node.js)
-
-![Project Status](https://img.shields.io/badge/status-beta-blue)
-![Version](https://img.shields.io/npm/v/@devaloop/devalang)
-![License: MIT](https://img.shields.io/badge/license-MIT-green)
-
-![Linux](https://img.shields.io/badge/linux-supported-blue?logo=linux)
-![macOS](https://img.shields.io/badge/macOS-supported-blue?logo=apple)
-![Windows](https://img.shields.io/badge/windows-supported-blue?logo=windows)
-
-![npm](https://img.shields.io/npm/dt/@devaloop/devalang)
-![crates](https://img.shields.io/crates/d/devalang)
-
-![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/devaloop-labs/devalang/.github/workflows/ci.yml)
-
-# 🦊 Devalang (CORE) — Compose music with code
-
-Devalang is a tiny domain-specific language (DSL) for music makers, sound designers, and audio hackers.
-Compose loops, control samples, render and play audio — all in clean, readable text.
-
-Whether you're building a track, shaping textures, or performing live, Devalang helps you think in rhythms. It’s designed to be simple, expressive, and fast — because your ideas shouldn’t wait.
-
-From studio sketches to live sets, Devalang gives you rhythmic control — with the elegance of code.
-
-> **🚧 Notice 🚧**
->
-> Includes synthesis, playback, and rendering features, but is still in early development, and breaking changes may occur.
->
-> **NEW**: [Devalang WORKSHOP is now available](https://workshop.devalang.com).
->
-
-## 📚 Quick Access
-
-- [▶️ Playground](https://playground.devalang.com)
-- [📖 Documentation](https://docs.devalang.com)
-- [🧩 VSCode Extension](https://marketplace.visualstudio.com/items?itemName=devaloop.devalang-vscode)
-- [🎨 Prettier Plugin](https://www.npmjs.com/package/@devaloop/prettier-plugin-devalang)
-- [📜 Changelog](./docs/CHANGELOG.md)
-- [💡 Examples](./examples/)
-- [🌐 Project Website](https://devalang.com)
-- [📦 Devaforge on npm](https://www.npmjs.com/package/@devaloop/devaforge)
-- [📦 Devalang on npm](https://www.npmjs.com/package/@devaloop/devalang)
-
-## ⏱️ Try it now !
-
-### Try Devalang in your browser
-
-> [Have a look at the Playground to try Devalang directly in your browser](https://playground.devalang.com)
-
-### Try Devalang in your terminal
-
-#### With Node.js
-
-```bash
-npm install -g @devaloop/devalang@latest
-```
-
-#### With Rust
-
-```bash
-cargo install devalang --version <version>
-```
-
-#### Initialize a new project
-
-```bash
-devalang init --name my-project --template minimal
-```
-
-#### Write your first script
-
-Create a new Devalang file `src/index.deva` in the project directory:
-
-```deva
-# src/index.deva
-
-# BPM definition
-bpm 125
-
-# Bank picking (make sure you've installed it)
-bank devaloop.808 as my808Bank
-
-# Pattern literal without options
-pattern kickPattern with my808Bank.kick = "x--- x--- x--- x---"
-
-group myGroup:
-    # Rhythmic (each beat playing a kick)
-    # on beat:
-    #     .my808Bank.kick 1/4
-
-    # Synth definition with ADSR
-    let myLead = synth sine {
-        attack: 0,
-        decay: 100,
-        sustain: 100,
-        release: 100
-    }
-
-    # Global automation
-    automate myLead:
-        param volume {
-            0% = 0.0
-            100% = 0.5
-        }
-        param pitch {
-            0% = -12.0
-            100% = 12.0
-        }
-
-    # Notes in a loop with condition
-    for i in [1, 2, 3]:
-        if i == 3:
-            myLead -> note(C5, { duration: 200 })
-            print "Playing note C5 for " + i
-
-    # Pause runtime for 500ms
-    sleep 500
-
-    # Note with automation
-    myLead -> note(C4, {
-        duration: 400,
-        velocity: 0.8,
-        automate: {
-            pan: {
-                0%: -1.0,
-                100%: 0.0
-            }
-        }
-    })
-
-    # Notes with params
-    myLead -> note(G4, { duration: 600, glide: true })
-    myLead -> note(B3, { duration: 400, slide: true })
-
-# Spawning the group & the pattern to play them in parallel
-spawn myGroup
-spawn kickPattern
-```
-
-### And the best part ? You can play it directly from the command line:
-
-#### Play the script once
-
-```bash
-devalang play
-```
-
-#### **LIVE mode** (repeat the playback + watch mode)
-
-```bash
-devalang play --repeat
-```
-
-### 🎉 You can now hear your Devalang code in action
-
-> For more examples, check out the [examples directory](./examples/)
-
-## ❓ Why Devalang ?
-
-- 🎹 Prototype audio ideas without opening a DAW, even VSCode with our Playground
-- 💻 Integrate sound into code-based workflows
-- 🎛️ Control audio parameters through readable syntax
-- 🧪 Build musical logic with variables and conditions
-- 🔄 Create complex patterns with ease
-
-## 🚀 Features
-
-- ⚡ **Fast Build & Hot Reload** — optimized build process for quicker iteration.
-- 🎵 **Audio Engine & Real-time runner** — low-latency playback, render-to-file, and a realtime runner used by `devalang play --repeat` for live feedback.
-- 🧩 **Language primitives** — synths, notes, ADSR, maps, arrays, loops, conditionals and functions for expressive musical logic.
-- 🎛️ **Per-note automation & modulators** — `automate` maps, `$mod.*`, `$easing.*` and `$math.*` helpers for envelopes and LFOs.
-- 🧩 **Module system & structured AST** — import/export variables, stable AST output for debugging and tooling.
-- 🧰 **Plugins & Addons (WASM-ready)** — install plugins/banks, `@use` directive, and WASM plugin integration so plugins can render or process audio at runtime.
-- 📦 **Addon manager & Devaforge** — CLI commands to discover/install banks, plugins and templates; `devaforge` helps create addons.
-- ⚙️ **CLI tooling** — `build`, `check`, `play`, `install`, `init`, `discover`, `telemetry` and more with consistent flags (`--watch`, `--debug`, `--compress`).
-- 📂 **Project templates & examples** — quick-start templates and many example projects in `examples/`.
-- 🧑‍💻 **TypeScript API & WASM distribution** — Node-friendly package with TypeScript bindings and a WASM build for browser/Node usage.
-- 🧰 **Editor & formatting support** — VSCode extension and Prettier plugin to edit Devalang with syntax and formatting support.
-- 🎵 **Custom samples & banks** — drop samples into `.deva` and reference them from code; banks of sounds for fast composition.
-- 🔄 **Looping, grouping & scheduling** — precise beat-tied scheduling primitives for complex rhythmic patterns.
-
-## 📄 Documentation
-
-### [Please refer to the online documentation](https://docs.devalang.com) for detailed information on syntax, features, and usage examples
-
-## 📰 What's new
-
-- **Effects chaining**: Added support for chaining multiple effects on synths and samples.
-- **New addons system**: Revamped the addons system for better management and integration.
-- **MIDI export**: Added the ability to export MIDI files from Devalang scripts.
-- **Synthesizer improvements**: Enhanced the built-in synthesizer with new types and modulation options.
-- **Devaforge**: Introduced a new system for creating and managing addons, including a CLI for addon generation.
-- **Documentation updates**: Improved documentation for clarity and completeness.
-- **Discovering addons**: Introduced a new command to detect addons.
-- **Public TypeScript API**: Added a public TypeScript API for easier integration.
-- **Improved error messages**: Enhanced error messages for better debugging.
-- **Major refactor**: Significant codebase refactor for improved maintainability and performance.
-- **Bug fixes**: Various bug fixes and stability improvements.
-
-## 🛡️ License
-
-MIT — see [LICENSE](./LICENSE)
-
-## 🤝 Contributing
-
-Contributions, bug reports and suggestions are welcome !  
-Feel free to open an issue or submit a pull request.
-
-For more info, see [docs/CONTRIBUTING.md](./docs/CONTRIBUTING.md).
-
-## 📢 Contact
-
-Feel free to reach out for any inquiries or feedback.
-
-📧 [contact@devaloop.com](mailto:contact@devaloop.com)
+<div align="center">
+    <img src="https://devalang.com/images/devalang-logo-min.png" alt="Devalang Logo" width="100" />
+</div>
+
+![Rust](https://img.shields.io/badge/Made%20with-Rust-orange?logo=rust)
+![TypeScript](https://img.shields.io/badge/Built%20with-TypeScript-blue?logo=typescript)
+![Node.js](https://img.shields.io/badge/Node.js-16%2B-brightgreen?logo=node.js)
+
+![Project Status](https://img.shields.io/badge/status-preview-blue)
+![Version](https://img.shields.io/npm/v/@devaloop/devalang)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+
+![Linux](https://img.shields.io/badge/linux-supported-blue?logo=linux)
+![macOS](https://img.shields.io/badge/macOS-supported-blue?logo=apple)
+![Windows](https://img.shields.io/badge/windows-supported-blue?logo=windows)
+
+![npm](https://img.shields.io/npm/dt/@devaloop/devalang)
+![crates](https://img.shields.io/crates/d/devalang)
+
+# 🦊 Devalang — Write music with code
+
+Devalang is a compact domain-specific language (DSL) for music makers, sound designers, and creative coders.
+Compose loops, control samples, synthesize audio, and render your ideas — all in clean, readable text.
+
+Whether you're prototyping a beat, building generative music, or performing live, Devalang gives you rhythmic precision with the elegance of code.
+
+From studio sketches to live sets, Devalang puts musical ideas into motion.
+
+> **🚀 v0.1.0 - Complete Rewriting**
+>
+>
+> **NEW**: [Devalang Playground V2.0 is now available](https://playground.devalang.com) — Try it in your browser!
+
+---
+
+## 📚 Quick Access
+
+- [▶️ Playground](https://playground.devalang.com) — Try Devalang in your browser
+- [📖 Documentation](https://docs.devalang.com) — Complete language reference
+- [🧩 VSCode Extension](https://marketplace.visualstudio.com/items?itemName=devaloop.devalang-vscode) — Syntax highlighting & snippets
+- [📜 Changelog](./docs/CHANGELOG.md) — Version history
+- [💡 Examples](./examples/)
+- [🌐 Website](https://devalang.com) — Project homepage
+- [📦 npm Package](https://www.npmjs.com/package/@devaloop/devalang)
+- [📦 Rust Crate](https://crates.io/crates/devalang)
+
+---
+
+## ⚡ Quick Start
+
+### Try in Your Browser
+
+> **[Launch the Playground](https://playground.devalang.com)** to try Devalang without installing anything.
+
+### Install via npm (Recommended)
+
+```bash
+npm install -g @devaloop/devalang
+```
+
+### Install via Cargo (Rust)
+
+```bash
+cargo install devalang
+```
+
+### Create Your First Project
+
+```bash
+# Initialize a new project
+devalang init my-project
+
+# Navigate to the project
+cd my-project
+
+# Check syntax
+devalang check --entry examples/index.deva
+
+# Build audio files
+devalang build --path examples/index.deva --formats wav mid
+
+# Play audio (live mode)
+devalang play --live --input examples/index.deva
+```
+
+---
+
+## 🎵 Your First Devalang Script
+
+Create a file `hello.deva`:
+
+```deva
+# Set the tempo
+bpm 120
+
+# Load a bank of sounds
+bank devaloop.808 as drums
+
+# Create a simple drum pattern
+pattern kickPattern with drums.kick = "x--- x--- x--- x---"
+pattern snarePattern with drums.snare = "---- x--- ---- x---"
+pattern hihatPattern with drums.hihat = "x-x- x-x- x-x- x-x-"
+
+# Play the patterns
+call kickPattern
+call snarePattern
+call hihatPattern
+```
+
+### Build the audio
+
+```bash
+# Build to WAV
+devalang build --path hello.deva --formats wav
+
+# Output: ./output/audio/hello.wav
+```
+
+# Play the audio
+
+```bash
+# Play the audio file
+devalang play --input hello.deva
+
+# Play live (repeats and watch until stopped)
+devalang play --live --input hello.deva
+```
+
+---
+
+## 🚀 Features
+
+### 🎵 **Core Language**
+- ✅ **Lexer & Parser** — Complete tokenization and AST generation
+- ✅ **Patterns** — Rhythmic notation with swing, humanize, velocity
+- ✅ **Synths** — Built-in synthesizers with ADSR envelopes
+- ✅ **Filters** — Lowpass, highpass, bandpass audio filtering
+- ✅ **Effects** — Reverb, delay, distortion, drive, chorus
+- ✅ **Variables** — `let`, `const`, `var` with scoping
+- ✅ **Groups & Spawn** — Organize and parallelize execution
+- ✅ **Loops & Conditions** — `for`, `if`, `else` control flow
+- ✅ **Triggers** — Conditional audio triggering
+- ✅ **Events** — Event system with `on` and `emit`
+
+### 🛠️ **CLI Tools**
+- ✅ `devalang init` — Scaffold new projects (3 templates)
+- ✅ `devalang build` — Compile to WAV/MIDI
+- ✅ `devalang check` — Validate syntax
+- ✅ `devalang play` — Audio playback
+- ✅ `devalang addon` — Manage addons (install, list, discover)
+- ✅ `devalang login/logout` — Authentication
+- ✅ `devalang telemetry` — Privacy controls
+
+### 🌐 **WASM API**
+- ✅ `render_audio()` — Browser audio rendering
+- ✅ `render_midi_array()` — MIDI export
+- ✅ `debug_render()` — Debug information
+- ✅ `parse()` — Parse Devalang code
+- ✅ TypeScript types included
+
+### 📦 **Output Formats**
+- ✅ **WAV** — 16/24/32-bit audio export
+- ✅ **MIDI** — Standard MIDI file export
+- ⚠️ **MP3/FLAC** — Planned for v0.1.1
+
+### 🎯 **Performance**
+- ⚡ **Fast builds** — 7-10ms for typical projects
+- ⚡ **Low latency** — Optimized audio engine
+- ⚡ **Release builds** — 5-6x faster than debug
+
+### 📚 **Learning Resources**
+- ✅ **Online Docs** — Complete language reference
+- ✅ **VSCode Extension** — Syntax highlighting
+
+---
+
+## 💡 Why Devalang?
+
+- 🎹 **Prototype audio ideas** without opening a DAW
+- 💻 **Integrate sound** into code-based workflows
+- 🎛️ **Control audio parameters** with readable syntax
+- 🧪 **Build musical logic** with variables and conditions
+- 🔄 **Create patterns** with expressive notation
+- 🎨 **Live code** with fast iteration cycles
+- 📦 **Version control** your music with git
+
+---
+
+## 📖 Documentation
+
+**[Visit docs.devalang.com](https://docs.devalang.com)** for:
+- Complete syntax reference
+- API documentation
+- WASM integration guide
+- CLI command reference
+- Advanced tutorials
+- Best practices
+
+---
+
+## 🔧 Development
+
+### Build from Source
+
+```bash
+# Clone the repository
+git clone https://github.com/devaloop-labs/devalang.git
+cd devalang
+
+# Build CLI (Rust)
+cargo build --release --features cli
+
+# Build WASM
+cargo build --release --features wasm --lib
+
+# Build TypeScript
+npm install
+npm run ts:build
+
+# Run tests
+cargo test --features cli
+npm test
+```
+
+## 🤝 Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+### Ways to Contribute
+
+- 🐛 **Report bugs** via [GitHub Issues](https://github.com/devaloop-labs/devalang/issues)
+- 💡 **Suggest features** in discussions
+- 📝 **Improve docs** with pull requests
+- 🎵 **Share examples** of your creations
+- 🧪 **Write tests** for new features
+
+---
+
+## 📜 License
+
+MIT License — See [LICENSE](./LICENSE) for details.
+
+Copyright (c) 2025 Devaloop
+
+---
+
+<div align="center">
+    <strong>Made with ❤️ by the Devaloop team</strong>
+    <br />
+    <sub>Star ⭐ the repo if you like it!</sub>
+</div>