@onda-lang/wasm-compiler 0.5.4 → 0.7.0

package/README.md

@@ -8,12 +8,12 @@ require LLVM, a Wasm linker, Rust, or `wasm-pack` after installation.
 import { createCompiler } from "@onda-lang/wasm-compiler";
 
 const compiler = await createCompiler();
-const artifact = await compiler.compileSource(source, {
+const { artifact, sourceFiles } = await compiler.compileSource(source, {
   sampleRate: 48_000,
   blockSize: 128,
 });
 
-console.log(artifact.wasm, artifact.metadata);
+console.log(artifact.wasm, artifact.metadata, sourceFiles);
 ```
 
 The package composes Onda's embedded Rust frontend with its Binaryen backend. The frontend emits
@@ -25,13 +25,13 @@ Release builds post-optimize the Rust frontend Wasm with the package's pinned Bi
 `dist/build.json`, and fails if the pass does not reduce the shipped module. Generated DSP modules
 are already optimized independently by the runtime Binaryen O4 pipeline.
 
-## Projects
+## Source workspaces
 
 Project compilation resolves imports and includes entirely from the supplied source map and the
 embedded standard library:
 
 ```js
-const artifact = await compiler.compileProject({
+const { artifact, sourceFiles } = await compiler.compileWorkspace({
   entry: "main.onda",
   sources: {
     "main.onda": mainSource,
@@ -41,10 +41,66 @@ const artifact = await compiler.compileProject({
   sampleRate: 48_000,
   blockSize: 128,
 });
+
+// Entry first, then transitive imports/includes. Embedded stdlib is excluded.
+console.log(sourceFiles);
 ```
 
 Compilation failures throw `OndaCompileError`. Its `diagnostics` property contains structured
-parse, semantic, MIR, configuration, or code-generation diagnostics.
+parse, semantic, MIR, configuration, or code-generation diagnostics. Its `sourceFiles` property
+contains every project source resolved before compilation stopped, allowing hosts to retain useful
+watch registrations while the project is temporarily invalid. `unresolvedSourceFiles` contains
+referenced non-standard-library candidates which were not present, allowing hosts to watch for their
+creation without treating them as contributing compilation inputs.
+
+## Portable project images
+
+Successful workspace compilation also returns `sourceGraph`, the exact documents and resolved
+import/include edges used for that build. Combine it with canonical typed buffers to create a
+portable project image:
+
+```js
+const compiled = await compiler.compileWorkspace(workspace, options);
+const sample = await compiler.encodeBufferAsset({
+  element: "f32",
+  frames: samples.length,
+  channels: 1,
+  sampleRate: 48_000,
+  data: new Float32Array(samples),
+});
+const image = await compiler.createProjectImage(
+  compiled.sourceGraph,
+  new Map([["sample", sample]]),
+);
+
+const replayed = await compiler.compileProjectImage(image.bytes, options);
+const exported = await compiler.materializeProjectImage(
+  image.bytes,
+  new Map([["sample", "recording.wav"]]),
+);
+
+// WAV and .ondabuffer inputs share the same canonical Rust decoder.
+const decoded = await compiler.decodeBufferFile(fileBytes, "sample.wav");
+```
+
+Project-image buffer maps use physical slot names. A scalar declaration uses its source name;
+fixed arrays use names such as `bank[0]` and `bank[1]`. Omitted slots remain unbound and neutral at
+runtime, so an image contains only the assets the project actually supplies.
+
+`materializeProjectImage` emits Onda's canonical publication layout: `code/main.onda`, meaningful
+source subdirectories below `code/`, and typed assets below `assets/`.
+`loadProjectFiles(files, projectFilePath?)` performs the reverse operation from a complete map of
+extracted project-relative files. Pass the `.ondaproject` path when the map contains multiple
+projects; manifests may occur in any directory and resolve their paths relative to that directory.
+Omitting it requires an unambiguous manifest. Loading rejects a reachable source graph
+that cannot be loaded and parsed. Portable project exports must be created from a successful
+compilation, as in the example above. `inspectProjectImage` validates an image and returns its
+source graph, logical buffer bindings, asset metadata, and content digest. `projectCapabilities`
+reports the immutable image, buffer-container, and embedded-standard-library versions. The worker
+client exposes the same methods and transfers binary payloads rather than cloning them.
+
+All canonical project and `.ondabuffer` serialization is implemented by the same Rust `onda_project`
+crate used by the native C API. JavaScript only adapts maps, typed arrays, and worker messages.
 
 ## Browser workers
 
@@ -52,7 +108,7 @@ Compilation is CPU-intensive. Use the built-in worker client in interactive brow
 
 ```js
 const compiler = await createCompiler({ worker: true });
-const artifact = await compiler.compileSource(source, options);
+const { artifact, sourceFiles } = await compiler.compileSource(source, options);
 await compiler.dispose();
 ```
 
@@ -99,7 +155,7 @@ await compiler.sendLspMessage({
 Open every virtual project file with `didOpen`; imports and includes resolve from those overlays and
 the embedded standard library. Diagnostics, semantic tokens, completion, hover, definitions, and
 document symbols use the native server implementation. The browser transport does not run MIR or a
-backend until the host explicitly calls `compileSource` or `compileProject`.
+backend until the host explicitly calls `compileSource` or `compileWorkspace`.
 
 ## CLI
 

package/bin/onda-wasm.js

@@ -72,7 +72,7 @@ export async function main(argv = process.argv.slice(2)) {
   const watOutput = parsed.watOut === undefined ? undefined : resolve(parsed.watOut);
   const compiler = await createCompiler();
   try {
-    const artifact = await compiler.compileProject({ entry, sources }, {
+    const { artifact } = await compiler.compileWorkspace({ entry, sources }, {
       sampleRate: parsed.sampleRate,
       blockSize: parsed.blockSize,
       codegen: {

package/dist/backend/artifact.d.ts

@@ -3,6 +3,8 @@ export {
   PROCESSOR_ABI_VERSION,
   PROCESSOR_ARTIFACT_FORMAT,
   PROCESSOR_ARTIFACT_FORMAT_VERSION,
+  PROCESSOR_EXECUTION_OK,
+  PROCESSOR_EXECUTION_RUNTIME_SAFETY_FAILURE,
   PROCESSOR_SNAPSHOT_FORMAT_VERSION,
   createProcessorArtifactFiles,
   loadProcessorArtifactFiles,

package/dist/backend/constants.js

@@ -1,2 +1,2 @@
 // Synchronized from format-versions.json; do not edit this copy directly.
-export const SUPPORTED_MIR_SCHEMA_VERSION = 1;
+export const SUPPORTED_MIR_SCHEMA_VERSION = 4;

package/dist/backend/index.d.ts

@@ -4,6 +4,8 @@ export {
   PROCESSOR_ABI_VERSION,
   PROCESSOR_ARTIFACT_FORMAT,
   PROCESSOR_ARTIFACT_FORMAT_VERSION,
+  PROCESSOR_EXECUTION_OK,
+  PROCESSOR_EXECUTION_RUNTIME_SAFETY_FAILURE,
   PROCESSOR_SNAPSHOT_FORMAT_VERSION,
   createProcessorArtifactFiles,
   loadProcessorArtifactFiles,