@devaloop/devalang 0.0.1-alpha.16-hotfix.1 → 0.0.1-alpha.17

package/templates/welcome/README.md

@@ -9,12 +9,15 @@
 ![Project Status](https://img.shields.io/badge/status-alpha-red)
 ![Version](https://img.shields.io/npm/v/@devaloop/devalang)
 ![License: MIT](https://img.shields.io/badge/license-MIT-green)
-![Platform](https://img.shields.io/badge/platform-Windows-blue)
+
+![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)
 
-[![VSCode Extension](https://img.shields.io/visual-studio-marketplace/v/devaloop.devalang-vscode?label=VSCode%20Extension)](https://marketplace.visualstudio.com/items?itemName=devaloop.devalang-vscode)
+![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
 
@@ -25,12 +28,13 @@ Whether you're building a track, shaping textures, or performing live, Devalang
 
 From studio sketches to live sets, Devalang gives you rhythmic control — with the elegance of code.
 
-> 🚧 Alpha Notice 🚧
+> **🚧 Notice 🚧**
+>
+> Includes synthesis, playback, and rendering features, but is still in early development, and breaking changes may occur.
 >
-> Includes synthesis, playback, and rendering features, but is still in early development.
+> **NEW**: [Devaforge is now available for creating addons](https://github.com/devaloop-labs/devaforge).
 >
-> Currently, Devalang CLI is only available for **Windows**.
-> Linux and macOS binaries will be added in future releases via cross-platform builds.
+> **NEW**: Now available for Windows, Linux, and macOS.
 
 ## 📚 Quick Access
 
@@ -41,81 +45,113 @@ From studio sketches to live sets, Devalang gives you rhythmic control — with
 - [📜 Changelog](./docs/CHANGELOG.md)
 - [💡 Examples](./examples/)
 - [🌐 Project Website](https://devalang.com)
-- [📦 Devalang CLI on npm](https://www.npmjs.com/package/@devaloop/devalang)
+- [📦 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](https://playground.devalang.com) to try Devalang directly in your browser
+> [Have a look at the Playground to try Devalang directly in your browser](https://playground.devalang.com)
 
-### Try Devalang CLI
+### Try Devalang in your terminal
+
+#### With Node.js
 
 ```bash
-# Install Devalang CLI globally
-npm install -g @devaloop/devalang
+npm install -g @devaloop/devalang@latest
+```
 
-# Create a new Devalang project
+#### With Rust
+
+```bash
+cargo install devalang
+```
+
+#### Initialize a new project (current directory)
+
+```bash
 devalang init --name my-project --template minimal
-cd my-project
 ```
 
+#### Write your first script
+
 Create a new Devalang file `src/index.deva` in the project directory:
 
 ```deva
 # src/index.deva
 
-group main:
-    let lead = synth sine {
+# BPM definition
+bpm 125
+
+# Bank picking (make sure you installed it)
+bank devaloop.808 as my808Bank
+
+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 for this synth (applies to subsequent notes)
-    automate lead:
+    # Global automation
+    automate myLead:
         param volume {
             0% = 0.0
-            100% = 1.0
-        }
-        param pan {
-            0% = -1.0
-            100% = 1.0
+            100% = 0.5
         }
         param pitch {
             0% = -12.0
             100% = 12.0
         }
 
-    lead -> note(C4, {
+    # 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 } }
+        automate: {
+            pan: {
+                0%: -1.0,
+                100%: 0.0
+            }
+        }
     })
 
-    lead -> note(E4, { duration: 400 })
-    lead -> note(G4, { duration: 600, glide: true, target_freq: 659.25 })
-    lead -> note(B3, { duration: 400, slide: true, target_amp: 0.3 })
+    # Notes with params
+    myLead -> note(E4, { duration: 400 })
+    myLead -> note(G4, { duration: 600, glide: true, target_freq: 659.25 })
+    myLead -> note(B3, { duration: 400, slide: true, target_amp: 0.3 })
 
-    for i in [1, 2, 3]:
-        lead -> note(C5, { duration: 200 })
-
-# Play the lead
-
-call main
+# Calling the group to play it
+call myGroup
 ```
 
 ### And the best part ? You can play it directly from the command line:
 
+#### Play the script once
+
 ```bash
-# Play the Devalang file
 devalang play
+```
 
-# Play the Devalang file with watch mode
-devalang play --watch
+#### **LIVE mode** (repeat the playback + watch mode)
 
-# LIVE mode (repeat the playback + watch mode)
+```bash
 devalang play --repeat
 ```
 
@@ -125,40 +161,48 @@ devalang play --repeat
 
 ## ❓ Why Devalang ?
 
-- 🎹 Prototype audio ideas without opening a DAW, even VSCode
+- 🎹 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
+- 🎚️ Automate everything
 
 ## 🚀 Features
 
-- 🎵 **Audio Engine**: Integrated audio playback and rendering
-- 🧩 **Module system** for importing and exporting variables between files
-- 📦 **Addon manager** for managing external banks, plugins and more
-- 📜 **Structured AST** generation for debugging and future compilation
-- 🔢 **Basic data types**: strings, numbers, booleans, maps, arrays
-- 👁️ **Watch mode** for `build`, `check` and `play` commands
-- 📂 **Project templates** for quick setup
-- 🎛️ **Custom samples**: easily load and trigger your own audio files
-- 🔄 **Looping and grouping**: create complex patterns with ease
+- ⚡ **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` for live feedback.
+- ▶️ **Live mode (watch + repeat)** — edit and hear changes instantly with `devalang play --repeat` and watch mode.
+- 🧩 **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
+### [Please refer to the online documentation](https://docs.devalang.com) for detailed information on syntax, features, and usage examples
 
-## 🧯 Known issues
+## 📰 What's new
 
-- No smart modules yet, all groups, variables, and samples must be explicitly imported where used
-- No support yet for cross-platform builds (Linux, macOS)
+- **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.
+- **Bug fixes**: Various bug fixes and stability improvements.
 
 ## 🧪 Roadmap Highlights
 
 For more info, see [docs/ROADMAP.md](./docs/ROADMAP.md)
 
-- ⏳ Other statements (e.g `function`, `pattern`, ...)
-- ⏳ Cross-platform support (Linux, macOS)
-- ⏳ More built-in instruments (e.g. snare, hi-hat, etc.)
+- ⏳ Smart modules
 
 ## 🛡️ License
 

package/templates/welcome/src/index.deva

@@ -1,13 +1,61 @@
-# 🦊 Welcome to Devalang !
-# This is your first Devalang program ?
-# Let's start with a simple example that plays a sample in a loop.
+# 🦊 Welcome to Devalang
+# Happy live-coding !
 
-@import { bpmVar, bankVar, loopVar } from './variables.deva'
-@load "../samples/kick-808.wav" as sample
+@import { bpmVar } from './variables.deva'
+@load "../samples/kick-808.wav" as myKick
 
+# BPM definition
 bpm bpmVar
 
-bank bankVar
+group myGroup:
+    # Rhythmic (each beat playing a kick)
+    on beat:
+        .myKick 1/4
 
-loop loopVar:
-    .sample auto
+    # 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(E4, { duration: 400 })
+    myLead -> note(G4, { duration: 600, glide: true, target_freq: 659.25 })
+    myLead -> note(B3, { duration: 400, slide: true, target_amp: 0.3 })
+
+# Calling the group to play it
+call myGroup

package/templates/welcome/src/variables.deva

@@ -1,5 +1,3 @@
-let bpmVar = 120
-let bankVar = 808
-let loopVar = 10
+let bpmVar = 135
 
-@export { bpmVar, bankVar, loopVar }
+@export { bpmVar }

package/tests/typescript/index.spec.ts

@@ -0,0 +1,136 @@
+import { expect } from "chai";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+// CommonJS bundle import (TypeScript-friendly)
+const core: any = require("../../out-tsc");
+
+describe("devalang typescript index", () => {
+  let origCwd: string;
+  let tmpDir: string | null = null;
+
+  before(function () {
+    // Prepare a temporary project root so wasm code that looks up project files
+    // and `.devalang` config can succeed during E2E runs.
+    origCwd = process.cwd();
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "devalang-e2e-"));
+    // Create minimal .devalang config file so get_project_root finds it
+    fs.writeFileSync(
+      path.join(tmpDir, ".devalang"),
+      'name = "devalang-test"\n'
+    );
+    // Ensure .deva exists (optional banks/plugins)
+    fs.mkdirSync(path.join(tmpDir, ".deva"), { recursive: true });
+    process.chdir(tmpDir);
+  });
+
+  after(function () {
+    // restore cwd and attempt cleanup
+    if (tmpDir) {
+      try {
+        process.chdir(origCwd);
+        // best-effort cleanup
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+      } catch (e) {
+        // ignore
+      }
+    }
+  });
+  it("should expose render_audio and return a Float32Array when wasm is available", function () {
+    // Prefer wasm binding if available
+    const wasmFn = core.pkg && core.pkg.render_audio;
+
+    const sampleProgram = `# simple program for tests
+bpm 120
+
+group myLead:
+  let mySynth = synth sine
+  mySynth -> note(C4, { duration: 400 })
+  mySynth -> note(G4, { duration: 400 })
+call myLead
+`;
+
+    if (typeof wasmFn === "function") {
+      try {
+        // Get parsed AST first for debugging
+        if (core.pkg && typeof core.pkg.parse === "function") {
+          try {
+            const parsed = core.pkg.parse("playground.deva", sampleProgram);
+            // parsed may be an object { ok, ast, errors } or a string
+            const astStr =
+              parsed && parsed.ast
+                ? parsed.ast
+                : typeof parsed === "string"
+                ? parsed
+                : JSON.stringify(parsed);
+            expect(astStr).to.match(/note|synth/i);
+          } catch (e) {
+            console.warn(
+              "[TEST DEBUG] parse() failed or returned non-standard result:",
+              e
+            );
+          }
+        }
+
+        const result = wasmFn(sampleProgram);
+        expect(result.constructor && result.constructor.name).to.match(
+          /Float32Array|Float64Array|ArrayBuffer|Uint8Array/
+        );
+      } catch (err: any) {
+        // If the wasm panicked because the audio buffer is empty, skip the test in this env.
+        const msg =
+          typeof err === "string"
+            ? err
+            : err && err.message
+            ? err.message
+            : String(err);
+        if (msg.includes("Audio buffer is empty")) {
+          // skip this test on environments where generating audio isn't supported
+          // eslint-disable-next-line no-invalid-this
+          this.skip();
+        }
+
+        throw err;
+      }
+
+      return;
+    }
+
+    // If wasm binding isn't available, ensure a runtime placeholder exists but don't call it
+    const runtimeFn = core.render_audio;
+    expect(runtimeFn).to.be.a("function");
+  });
+
+  it("should find statements for entry module", function () {
+    const parseFn = core.pkg && core.pkg.parse;
+    if (typeof parseFn !== "function") {
+      // nothing to test if parse binding missing
+      // eslint-disable-next-line no-invalid-this
+      this.skip();
+    }
+
+    try {
+      const res = parseFn("playground.deva", "bpm 120");
+      expect(res).to.be.an("object");
+      // prefer explicit shape when available
+      if (Object.prototype.hasOwnProperty.call(res, "ok")) {
+        expect(res.ok).to.equal(true);
+      } else {
+        expect(res).to.have.property("ast");
+      }
+    } catch (err: any) {
+      const msg = err && err.message ? err.message : String(err);
+      if (
+        msg.includes("Module loading error") ||
+        msg.includes("Project root not found")
+      ) {
+        // environment not prepared for module loading, skip
+        // eslint-disable-next-line no-invalid-this
+        this.skip();
+        return;
+      }
+      throw err;
+    }
+  });
+});

package/tests/typescript/playhead.spec.ts

@@ -0,0 +1,36 @@
+import { expect } from "chai";
+
+const core: any = require("../../out-tsc");
+
+describe("playhead callback", () => {
+  it("should call registered callback during run", () => {
+    const register = core.pkg && core.pkg.register_playhead_callback;
+    const unregister = core.pkg && core.pkg.unregister_playhead_callback;
+    if (typeof register !== "function") {
+      // skip when wasm not available
+      return;
+    }
+
+    let called = false;
+    const cb = (ev: any) => {
+      called = true;
+      expect(ev).to.have.property("time");
+      expect(ev).to.have.property("line");
+      expect(ev).to.have.property("column");
+    };
+
+    register(cb);
+
+    // run a simple program to trigger events
+    const program = `bpm 120\n\n.myTrigger 1/4\n`;
+    // render_audio will schedule triggers and should invoke the callback during execution
+    const render = core.pkg && core.pkg.render_audio;
+    if (typeof render === "function") {
+      render(program);
+    }
+
+    unregister && unregister();
+
+    expect(called).to.be.true;
+  });
+});

package/tests/typescript/render_e2e.spec.ts

@@ -0,0 +1,77 @@
+import { expect } from "chai";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+const core: any = require("../../out-tsc");
+
+describe("devalang debug_render and render_audio E2E", () => {
+  let origCwd: string;
+  let tmpDir: string | null = null;
+
+  before(function () {
+    origCwd = process.cwd();
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "devalang-e2e-"));
+    fs.writeFileSync(
+      path.join(tmpDir, ".devalang"),
+      'name = "devalang-test"\n'
+    );
+    fs.mkdirSync(path.join(tmpDir, ".deva"), { recursive: true });
+    process.chdir(tmpDir as string);
+  });
+
+  after(function () {
+    if (tmpDir) {
+      try {
+        process.chdir(origCwd);
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+      } catch (e) {
+        // ignore
+      }
+    }
+  });
+
+  it("debug_render should return diagnostics including note_count and global_vars", function () {
+    const dbg = core.pkg && core.pkg.debug_render;
+    if (typeof dbg !== "function") {
+      // skip if wasm binding missing
+      // eslint-disable-next-line no-invalid-this
+      this.skip();
+    }
+
+    const sampleProgram = `# sample program\nbpm 120\n\ngroup myLead:\n  let mySynth = synth sine\n  mySynth -> note(C4, { duration: 400 })\n  mySynth -> note(G4, { duration: 400 })\ncall myLead\n`;
+
+    const out = dbg(sampleProgram);
+    expect(out).to.be.an("object");
+    expect(out).to.have.property("samples_len");
+    expect(out).to.have.property("any_nonzero");
+    expect(out).to.have.property("note_count");
+    expect(out).to.have.property("global_vars");
+
+    // Basic assertions: at least one non-zero sample or note_count > 0
+    expect(out.note_count).to.be.at.least(0);
+    expect(out.global_vars).to.include("myLead");
+  });
+
+  it("render_audio should return a Float32Array and not be completely silent", function () {
+    const render = (core.pkg && core.pkg.render_audio) || core.render_audio;
+    if (typeof render !== "function") {
+      // eslint-disable-next-line no-invalid-this
+      this.skip();
+    }
+
+    const sampleProgram = `# sample program\nbpm 120\n\ngroup myLead:\n  let mySynth = synth sine\n  mySynth -> note(C4, { duration: 400 })\n  mySynth -> note(G4, { duration: 400 })\ncall myLead\n`;
+
+    const arr = render(sampleProgram);
+    // If wasm returns JS typed array wrapper, check constructor name
+    expect(arr.constructor && arr.constructor.name).to.match(
+      /Float32Array|Float64Array|ArrayBuffer|Uint8Array/
+    );
+
+    // Convert to plain array if needed
+    const samples: number[] = Array.from(arr as any);
+    // Expect either note_count > 0 indirectly via nonzero samples
+    const anyNonZero = samples.some((s) => s !== 0);
+    expect(anyNonZero).to.be.true;
+  });
+});

package/tsconfig.json

@@ -52,7 +52,7 @@
     // "maxNodeModuleJsDepth": 1,                        /* Specify the maximum folder depth used for checking JavaScript files from 'node_modules'. Only applicable with 'allowJs'. */
 
     /* Emit */
-    // "declaration": true,                              /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
+    "declaration": true,                              /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
     // "declarationMap": true,                           /* Create sourcemaps for d.ts files. */
     // "emitDeclarationOnly": true,                      /* Only output d.ts files and not JavaScript files. */
     // "sourceMap": true,                                /* Create source map files for emitted JavaScript files. */

package/typescript/core/functions/index.ts

@@ -0,0 +1,83 @@
+import { ParseResult } from "../types/result";
+import { DebugResult } from "../types/result";
+
+let wasmPkg: any = undefined;
+try {
+  // prefer runtime pkg generated by wasm-pack when available
+  // require at runtime so the package can be used even if wasm hasn't been built
+  // (this keeps tests and consumers robust).
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  wasmPkg = require("../../pkg/devalang_core");
+} catch (_e) {
+  wasmPkg = undefined;
+}
+
+/**
+ * Parses the user code.
+ * @param entry_path The entry path for the code.
+ * @param source The source code to parse.
+ * @returns ParseResult | any
+ */
+export function parse(entry_path: string, source: string): ParseResult | any {
+  if (wasmPkg && typeof wasmPkg.parse === "function") {
+    return wasmPkg.parse(entry_path, source);
+  }
+
+  throw new Error(
+    "WASM binding 'parse' not available. Build the wasm package or use the JS runtime."
+  );
+}
+
+/**
+ * Renders the debug information for the user code.
+ * @param user_code The user-provided code to render debug information for.
+ * @returns DebugResult | any
+ */
+export function debug_render(user_code: string): DebugResult | any {
+  if (wasmPkg && typeof wasmPkg.debug_render === "function") {
+    return wasmPkg.debug_render(user_code);
+  }
+
+  throw new Error(
+    "WASM binding 'debug_render' not available. Build the wasm package or use the JS runtime."
+  );
+}
+
+/**
+ * Renders audio from the user code.
+ * @param user_code The user-provided code to render audio from.
+ * @returns Float32Array
+ */
+export function render_audio(user_code: string): Float32Array {
+  if (wasmPkg && typeof wasmPkg.render_audio === "function") {
+    return wasmPkg.render_audio(user_code);
+  }
+
+  // Fallback: indicate missing wasm with an empty buffer rather than breaking consumers.
+  return new Float32Array(0);
+}
+
+/**
+ * Register a JS callback to receive playhead events { time, line, column } during playback.
+ * The callback will be called with a single object argument.
+ * @param cb The callback function to register.
+ * @returns void
+ */
+export function register_playhead_callback(cb: (ev: { time: number; line: number; column: number }) => void) {
+  if (wasmPkg && typeof wasmPkg.register_playhead_callback === "function") {
+    return wasmPkg.register_playhead_callback(cb);
+  }
+  // no-op fallback
+  return;
+}
+
+/**
+ * Unregisters the JS callback for playhead events.
+ * @returns void
+ */
+export function unregister_playhead_callback() {
+  if (wasmPkg && typeof wasmPkg.unregister_playhead_callback === "function") {
+    return wasmPkg.unregister_playhead_callback();
+  }
+  return;
+}

package/typescript/core/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Core functionality for the Devalang language.
+ * This module exports all the core types and functions used in the language.
+ */
+export * from "./types/index";
+export * from "./functions/index";