miniray 0.1.1 → 0.1.3

package/README.md

@@ -75,11 +75,15 @@ Minify WGSL source code.
 
 ```typescript
 interface MinifyOptions {
-  minifyWhitespace?: boolean;        // Remove whitespace (default: true)
-  minifyIdentifiers?: boolean;       // Rename identifiers (default: true)
-  minifySyntax?: boolean;            // Optimize syntax (default: true)
-  mangleExternalBindings?: boolean;  // Mangle uniform/storage names (default: false)
-  keepNames?: string[];              // Names to preserve from renaming
+  minifyWhitespace?: boolean;           // Remove whitespace (default: true)
+  minifyIdentifiers?: boolean;          // Rename identifiers (default: true)
+  minifySyntax?: boolean;               // Optimize syntax (default: true)
+  mangleExternalBindings?: boolean;     // Mangle uniform/storage names (default: false)
+  treeShaking?: boolean;                // Remove unused declarations (default: true)
+  preserveUniformStructTypes?: boolean; // Keep struct types used in uniforms (default: false)
+  keepNames?: string[];                 // Names to preserve from renaming
+  sourceMap?: boolean;                  // Generate source map (default: false)
+  sourceMapSources?: boolean;           // Include source in sourcesContent (default: false)
 }
 
 interface MinifyResult {
@@ -87,6 +91,7 @@ interface MinifyResult {
   errors: MinifyError[];  // Parse/minification errors
   originalSize: number;   // Input size in bytes
   minifiedSize: number;   // Output size in bytes
+  sourceMap?: string;     // Source map JSON (if sourceMap: true)
 }
 ```
 
@@ -133,6 +138,40 @@ fn getValue() -> f32 { return uniforms * 2.0; }
 // Output: "@group(0) @binding(0) var<uniform> a:f32;fn b()->f32{return a*2.0;}"
 ```
 
+### `treeShaking`
+
+Enable dead code elimination to remove unused declarations (default: `true`):
+
+```javascript
+minify(source, {
+  treeShaking: true,  // Remove unreachable code
+});
+```
+
+### `preserveUniformStructTypes`
+
+Automatically preserve struct type names that are used in `var<uniform>` or `var<storage>` declarations (default: `false`):
+
+```javascript
+// Input
+const shader = `
+struct MyUniforms { time: f32 }
+@group(0) @binding(0) var<uniform> u: MyUniforms;
+@fragment fn main() -> @location(0) vec4f { return vec4f(u.time); }
+`;
+
+// With preserveUniformStructTypes: false (default)
+// struct MyUniforms -> struct a
+
+// With preserveUniformStructTypes: true
+// struct MyUniforms preserved
+minify(source, {
+  preserveUniformStructTypes: true,
+});
+```
+
+This is particularly useful for frameworks like PNGine that detect builtin uniforms by struct type name.
+
 ### `keepNames`
 
 Array of identifier names that should not be renamed:
@@ -144,6 +183,85 @@ minify(source, {
 });
 ```
 
+### `sourceMap`
+
+Generate a source map to debug minified shaders by mapping back to original source:
+
+```javascript
+const result = minify(source, {
+  minifyIdentifiers: true,
+  sourceMap: true,
+});
+
+console.log(result.code);
+// "const a=42;fn b()->i32{return a;}"
+
+console.log(result.sourceMap);
+// '{"version":3,"sources":[],"names":["longVariable","myFunction"],"mappings":"MAAAA,..."}'
+```
+
+The source map follows the [Source Map v3 specification](https://sourcemaps.info/spec.html) and includes:
+- `version`: Always 3
+- `names`: Original names of renamed identifiers
+- `mappings`: VLQ-encoded position mappings
+
+### `sourceMapSources`
+
+Include the original source code in the source map's `sourcesContent` field for self-contained debugging:
+
+```javascript
+const result = minify(source, {
+  sourceMap: true,
+  sourceMapSources: true,  // Embed original source
+});
+
+const map = JSON.parse(result.sourceMap);
+console.log(map.sourcesContent);
+// ["const longVariable = 42;\nfn myFunction() -> i32 { return longVariable; }"]
+```
+
+### Source Map Example: Complete Workflow
+
+```javascript
+import { initialize, minify } from 'miniray';
+
+await initialize({ wasmURL: '/miniray.wasm' });
+
+const source = `
+const longVariableName = 42;
+
+fn helperFunction(value: i32) -> i32 {
+    return value * 2;
+}
+
+@compute @workgroup_size(1)
+fn main() {
+    let result = helperFunction(longVariableName);
+}
+`;
+
+const result = minify(source, {
+  minifyWhitespace: true,
+  minifyIdentifiers: true,
+  sourceMap: true,
+  sourceMapSources: true,
+});
+
+console.log('Minified code:');
+console.log(result.code);
+// "const a=42;fn b(c:i32)->i32{return c*2;}@compute @workgroup_size(1) fn main(){let d=b(a);}"
+
+console.log('\nSource map:');
+const map = JSON.parse(result.sourceMap);
+console.log('Names:', map.names);
+// Names: ["longVariableName", "helperFunction", "value", "result"]
+
+// To use the source map inline:
+const codeWithSourceMap = result.code +
+  '\n//# sourceMappingURL=data:application/json;base64,' +
+  btoa(result.sourceMap);
+```
+
 ## Using with Bundlers
 
 ### Vite

package/lib/main.d.ts

@@ -29,6 +29,20 @@ export interface MinifyOptions {
    */
   mangleExternalBindings?: boolean;
 
+  /**
+   * Enable dead code elimination to remove unused declarations.
+   * @default true
+   */
+  treeShaking?: boolean;
+
+  /**
+   * Automatically preserve struct type names that are used in
+   * var<uniform> or var<storage> declarations.
+   * Useful for frameworks that detect uniforms by struct type name.
+   * @default false
+   */
+  preserveUniformStructTypes?: boolean;
+
   /**
    * Identifier names that should not be renamed.
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miniray",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "WGSL minifier for WebGPU shaders - WebAssembly build",
   "main": "lib/main.js",
   "module": "esm/browser.js",