miniray 0.1.1

package/README.md

@@ -0,0 +1,188 @@
+# miniray
+
+WGSL minifier for WebGPU shaders - WebAssembly build.
+
+This package provides a WASM build of the [miniray](https://github.com/HugoDaniel/miniray) that runs in browsers and Node.js.
+
+## Installation
+
+```bash
+npm install miniray
+```
+
+## Browser Usage
+
+```html
+<script src="node_modules/miniray/wasm_exec.js"></script>
+<script src="node_modules/miniray/lib/browser.js"></script>
+<script>
+  (async () => {
+    await miniray.initialize({ wasmURL: 'node_modules/miniray/miniray.wasm' });
+
+    const result = miniray.minify(`
+      @vertex fn main() -> @builtin(position) vec4f {
+        return vec4f(0.0);
+      }
+    `);
+
+    console.log(result.code);
+    // "@vertex fn main()->@builtin(position) vec4f{return vec4f(0.0);}"
+  })();
+</script>
+```
+
+### ESM Usage
+
+```javascript
+import { initialize, minify } from 'miniray';
+
+await initialize({ wasmURL: '/path/to/miniray.wasm' });
+
+const result = minify(source, {
+  minifyWhitespace: true,
+  minifyIdentifiers: true,
+  minifySyntax: true,
+});
+```
+
+## Node.js Usage
+
+```javascript
+const { initialize, minify } = require('miniray');
+
+await initialize(); // Automatically finds miniray.wasm
+
+const result = minify(source);
+console.log(result.code);
+```
+
+## API
+
+### `initialize(options)`
+
+Initialize the WASM module. Must be called before `minify()`.
+
+```typescript
+interface InitializeOptions {
+  wasmURL?: string | URL;           // Path or URL to miniray.wasm
+  wasmModule?: WebAssembly.Module;  // Pre-compiled module
+}
+```
+
+### `minify(source, options?)`
+
+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
+}
+
+interface MinifyResult {
+  code: string;           // Minified code
+  errors: MinifyError[];  // Parse/minification errors
+  originalSize: number;   // Input size in bytes
+  minifiedSize: number;   // Output size in bytes
+}
+```
+
+### `isInitialized()`
+
+Returns `true` if the WASM module is initialized.
+
+### `version`
+
+The version of the minifier.
+
+## Options
+
+### `minifyWhitespace`
+
+Remove unnecessary whitespace and newlines.
+
+### `minifyIdentifiers`
+
+Rename local variables, function parameters, and helper functions to shorter names. Entry points and API-facing declarations are preserved.
+
+### `minifySyntax`
+
+Apply syntax-level optimizations like numeric literal shortening.
+
+### `mangleExternalBindings`
+
+Control how `var<uniform>` and `var<storage>` names are handled:
+
+- `false` (default): Original names are preserved in declarations, short aliases are used internally. This maintains compatibility with WebGPU's binding reflection APIs.
+- `true`: Names are mangled directly for smaller output, but breaks binding reflection.
+
+```javascript
+// Input
+const shader = `
+@group(0) @binding(0) var<uniform> uniforms: f32;
+fn getValue() -> f32 { return uniforms * 2.0; }
+`;
+
+// With mangleExternalBindings: false (default)
+// Output: "@group(0) @binding(0) var<uniform> uniforms:f32;let a=uniforms;fn b()->f32{return a*2.0;}"
+
+// With mangleExternalBindings: true
+// Output: "@group(0) @binding(0) var<uniform> a:f32;fn b()->f32{return a*2.0;}"
+```
+
+### `keepNames`
+
+Array of identifier names that should not be renamed:
+
+```javascript
+minify(source, {
+  minifyIdentifiers: true,
+  keepNames: ['myHelper', 'computeValue'],
+});
+```
+
+## Using with Bundlers
+
+### Vite
+
+```javascript
+import { initialize, minify } from 'miniray';
+import wasmURL from 'miniray/miniray.wasm?url';
+
+await initialize({ wasmURL });
+```
+
+### Webpack
+
+```javascript
+import { initialize, minify } from 'miniray';
+
+// Configure webpack to handle .wasm files
+await initialize({ wasmURL: new URL('miniray/miniray.wasm', import.meta.url) });
+```
+
+## Pre-compiling WASM
+
+For better performance when creating multiple instances:
+
+```javascript
+const wasmModule = await WebAssembly.compileStreaming(
+  fetch('/miniray.wasm')
+);
+
+// Share module across workers
+await initialize({ wasmModule });
+```
+
+## Performance
+
+- WASM binary: ~3.6MB
+- Initialization: ~100ms (first load)
+- Transform: <1ms for typical shaders
+
+## License
+
+MIT

package/bin/miniray

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+
+function printUsage() {
+  console.log(`Usage: miniray [options] [file]
+
+Options:
+  -h, --help                  Show this help message
+  -v, --version               Show version
+  -o, --output <file>         Output file (default: stdout)
+  --no-mangle                 Disable identifier minification
+  --no-whitespace             Disable whitespace minification
+  --mangle-external-bindings  Mangle uniform/storage variable names
+  --keep-names <names>        Comma-separated list of names to preserve
+  --config <file>             Load config from JSON file
+
+If no file is specified, reads from stdin.
+
+Examples:
+  miniray shader.wgsl
+  miniray shader.wgsl -o shader.min.wgsl
+  miniray --keep-names main,uniforms shader.wgsl
+  cat shader.wgsl | miniray > shader.min.wgsl
+`);
+}
+
+function printVersion() {
+  const pkg = require('../package.json');
+  console.log(`miniray ${pkg.version}`);
+}
+
+// Parse options
+let inputFile = null;
+let outputFile = null;
+let options = {
+  minifyWhitespace: true,
+  minifyIdentifiers: true,
+  minifySyntax: true,
+  mangleExternalBindings: false,
+  keepNames: []
+};
+let configFile = null;
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+
+  if (arg === '-h' || arg === '--help') {
+    printUsage();
+    process.exit(0);
+  } else if (arg === '-v' || arg === '--version') {
+    printVersion();
+    process.exit(0);
+  } else if (arg === '-o' || arg === '--output') {
+    outputFile = args[++i];
+  } else if (arg === '--no-mangle') {
+    options.minifyIdentifiers = false;
+  } else if (arg === '--no-whitespace') {
+    options.minifyWhitespace = false;
+  } else if (arg === '--mangle-external-bindings') {
+    options.mangleExternalBindings = true;
+  } else if (arg === '--keep-names') {
+    options.keepNames = args[++i].split(',').map(s => s.trim());
+  } else if (arg === '--config') {
+    configFile = args[++i];
+  } else if (!arg.startsWith('-')) {
+    inputFile = arg;
+  } else {
+    console.error(`Unknown option: ${arg}`);
+    process.exit(1);
+  }
+}
+
+// Load config file if specified
+if (configFile) {
+  try {
+    const config = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+    if (config.minifyWhitespace !== undefined) options.minifyWhitespace = config.minifyWhitespace;
+    if (config.minifyIdentifiers !== undefined) options.minifyIdentifiers = config.minifyIdentifiers;
+    if (config.minifySyntax !== undefined) options.minifySyntax = config.minifySyntax;
+    if (config.mangleExternalBindings !== undefined) options.mangleExternalBindings = config.mangleExternalBindings;
+    if (config.keepNames) options.keepNames = [...options.keepNames, ...config.keepNames];
+  } catch (err) {
+    console.error(`Error loading config file: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+async function main() {
+  // Read input
+  let source;
+  if (inputFile) {
+    try {
+      source = fs.readFileSync(inputFile, 'utf8');
+    } catch (err) {
+      console.error(`Error reading file: ${err.message}`);
+      process.exit(1);
+    }
+  } else {
+    // Read from stdin
+    source = fs.readFileSync(0, 'utf8');
+  }
+
+  // Initialize WASM and minify
+  const { initialize, minify } = require('../lib/main.js');
+
+  try {
+    await initialize();
+    const result = minify(source, options);
+
+    if (result.errors && result.errors.length > 0) {
+      for (const err of result.errors) {
+        console.error(`Error at line ${err.line}, column ${err.column}: ${err.message}`);
+      }
+      process.exit(1);
+    }
+
+    // Write output
+    if (outputFile) {
+      fs.writeFileSync(outputFile, result.code);
+    } else {
+      process.stdout.write(result.code);
+    }
+  } catch (err) {
+    console.error(`Minification error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/esm/browser.js

@@ -0,0 +1,166 @@
+/**
+ * miniray - WGSL Minifier for WebGPU Shaders (ESM Build)
+ *
+ * Usage:
+ *   import { initialize, minify } from 'miniray'
+ *   await initialize({ wasmURL: '/miniray.wasm' })
+ *   const result = minify(source, { minifyWhitespace: true })
+ */
+
+let _initialized = false;
+let _initPromise = null;
+let _go = null;
+
+/**
+ * Initialize the WASM module.
+ * @param {Object} options
+ * @param {string|URL} [options.wasmURL] - URL to miniray.wasm
+ * @param {WebAssembly.Module} [options.wasmModule] - Pre-compiled module
+ * @returns {Promise<void>}
+ */
+export async function initialize(options) {
+  if (_initialized) {
+    return;
+  }
+  if (_initPromise) {
+    return _initPromise;
+  }
+
+  options = options || {};
+  const wasmURL = options.wasmURL;
+  const wasmModule = options.wasmModule;
+
+  if (!wasmURL && !wasmModule) {
+    throw new Error('Must provide either wasmURL or wasmModule');
+  }
+
+  _initPromise = _doInitialize(wasmURL, wasmModule);
+
+  try {
+    await _initPromise;
+    _initialized = true;
+  } catch (err) {
+    _initPromise = null;
+    throw err;
+  }
+}
+
+async function _doInitialize(wasmURL, wasmModule) {
+  // Load wasm_exec.js if Go is not defined
+  if (typeof Go === 'undefined') {
+    throw new Error(
+      'Go runtime not found. Make sure to include wasm_exec.js before using miniray:\n' +
+      '<script src="wasm_exec.js"></script>'
+    );
+  }
+
+  _go = new Go();
+
+  let instance;
+  if (wasmModule) {
+    // Use pre-compiled module
+    instance = await WebAssembly.instantiate(wasmModule, _go.importObject);
+  } else {
+    // Fetch and instantiate
+    const url = wasmURL instanceof URL ? wasmURL.href : wasmURL;
+
+    if (typeof WebAssembly.instantiateStreaming === 'function') {
+      try {
+        const response = await fetch(url);
+        if (!response.ok) {
+          throw new Error(`Failed to fetch ${url}: ${response.status}`);
+        }
+        const result = await WebAssembly.instantiateStreaming(response, _go.importObject);
+        instance = result.instance;
+      } catch (err) {
+        // Fall back to arrayBuffer if streaming fails (e.g., wrong MIME type)
+        if (err.message && err.message.includes('MIME')) {
+          const response = await fetch(url);
+          const bytes = await response.arrayBuffer();
+          const result = await WebAssembly.instantiate(bytes, _go.importObject);
+          instance = result.instance;
+        } else {
+          throw err;
+        }
+      }
+    } else {
+      // Fallback for older browsers
+      const response = await fetch(url);
+      const bytes = await response.arrayBuffer();
+      const result = await WebAssembly.instantiate(bytes, _go.importObject);
+      instance = result.instance;
+    }
+  }
+
+  // Run the Go program (this sets up __miniray global)
+  _go.run(instance);
+
+  // Wait for __miniray to be available
+  await _waitForGlobal('__miniray', 1000);
+}
+
+function _waitForGlobal(name, timeout) {
+  return new Promise((resolve, reject) => {
+    const start = Date.now();
+    const check = () => {
+      if (typeof globalThis[name] !== 'undefined') {
+        resolve();
+      } else if (Date.now() - start > timeout) {
+        reject(new Error(`Timeout waiting for ${name} to be defined`));
+      } else {
+        setTimeout(check, 10);
+      }
+    };
+    check();
+  });
+}
+
+/**
+ * Minify WGSL source code.
+ * @param {string} source - WGSL source code
+ * @param {Object} [options] - Minification options
+ * @param {boolean} [options.minifyWhitespace=true] - Remove whitespace
+ * @param {boolean} [options.minifyIdentifiers=true] - Rename identifiers
+ * @param {boolean} [options.minifySyntax=true] - Optimize syntax
+ * @param {boolean} [options.mangleExternalBindings=false] - Mangle uniform/storage names
+ * @param {string[]} [options.keepNames] - Names to preserve
+ * @returns {Object} Result with code, errors, originalSize, minifiedSize
+ */
+export function minify(source, options) {
+  if (!_initialized) {
+    throw new Error('miniray not initialized. Call initialize() first.');
+  }
+
+  if (typeof source !== 'string') {
+    throw new Error('source must be a string');
+  }
+
+  return globalThis.__miniray.minify(source, options || {});
+}
+
+/**
+ * Check if initialized.
+ * @returns {boolean}
+ */
+export function isInitialized() {
+  return _initialized;
+}
+
+/**
+ * Get version (available after initialization).
+ * @type {string}
+ */
+export const version = (() => {
+  // Getter that returns version after init
+  return {
+    toString() {
+      return _initialized ? globalThis.__miniray.version : 'unknown';
+    },
+    valueOf() {
+      return _initialized ? globalThis.__miniray.version : 'unknown';
+    }
+  };
+})();
+
+// Default export for convenience
+export default { initialize, minify, isInitialized, version };

package/esm/node.mjs

@@ -0,0 +1,152 @@
+/**
+ * miniray - WGSL Minifier for WebGPU Shaders (Node.js ESM Build)
+ *
+ * Usage:
+ *   import { initialize, minify } from 'miniray'
+ *   await initialize()
+ *   const result = minify(source, { minifyWhitespace: true })
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const require = createRequire(import.meta.url);
+
+let _initialized = false;
+let _initPromise = null;
+let _go = null;
+
+/**
+ * Initialize the WASM module.
+ * @param {Object} options
+ * @param {string} [options.wasmURL] - Path to miniray.wasm
+ * @param {WebAssembly.Module} [options.wasmModule] - Pre-compiled module
+ * @returns {Promise<void>}
+ */
+export async function initialize(options) {
+  if (_initialized) {
+    return;
+  }
+  if (_initPromise) {
+    return _initPromise;
+  }
+
+  options = options || {};
+  let wasmURL = options.wasmURL;
+  const wasmModule = options.wasmModule;
+
+  // Default to miniray.wasm in the package directory
+  if (!wasmURL && !wasmModule) {
+    wasmURL = path.join(__dirname, '..', 'miniray.wasm');
+  }
+
+  _initPromise = _doInitialize(wasmURL, wasmModule);
+
+  try {
+    await _initPromise;
+    _initialized = true;
+  } catch (err) {
+    _initPromise = null;
+    throw err;
+  }
+}
+
+async function _doInitialize(wasmURL, wasmModule) {
+  // Load wasm_exec.js - this defines Go globally
+  const wasmExecPath = path.join(__dirname, '..', 'wasm_exec.js');
+  if (!fs.existsSync(wasmExecPath)) {
+    throw new Error(`wasm_exec.js not found at ${wasmExecPath}`);
+  }
+
+  // Use require to load wasm_exec.js since it modifies globalThis
+  require(wasmExecPath);
+
+  if (typeof globalThis.Go === 'undefined') {
+    throw new Error('Go runtime not found after loading wasm_exec.js');
+  }
+
+  _go = new globalThis.Go();
+
+  let instance;
+  if (wasmModule) {
+    instance = await WebAssembly.instantiate(wasmModule, _go.importObject);
+  } else {
+    const wasmPath = wasmURL instanceof URL ? wasmURL.pathname : wasmURL;
+    const wasmBuffer = fs.readFileSync(wasmPath);
+    const result = await WebAssembly.instantiate(wasmBuffer, _go.importObject);
+    instance = result.instance;
+  }
+
+  // Run the Go program
+  _go.run(instance);
+
+  // Wait for __miniray to be available
+  await _waitForGlobal('__miniray', 1000);
+}
+
+function _waitForGlobal(name, timeout) {
+  return new Promise((resolve, reject) => {
+    const start = Date.now();
+    const check = () => {
+      if (typeof globalThis[name] !== 'undefined') {
+        resolve();
+      } else if (Date.now() - start > timeout) {
+        reject(new Error(`Timeout waiting for ${name} to be defined`));
+      } else {
+        setTimeout(check, 10);
+      }
+    };
+    check();
+  });
+}
+
+/**
+ * Minify WGSL source code.
+ * @param {string} source - WGSL source code
+ * @param {Object} [options] - Minification options
+ * @returns {Object} Result
+ */
+export function minify(source, options) {
+  if (!_initialized) {
+    throw new Error('miniray not initialized. Call initialize() first.');
+  }
+
+  if (typeof source !== 'string') {
+    throw new Error('source must be a string');
+  }
+
+  return globalThis.__miniray.minify(source, options || {});
+}
+
+/**
+ * Check if initialized.
+ * @returns {boolean}
+ */
+export function isInitialized() {
+  return _initialized;
+}
+
+/**
+ * Get version.
+ * @returns {string}
+ */
+export function getVersion() {
+  if (!_initialized) {
+    return 'unknown';
+  }
+  return globalThis.__miniray.version;
+}
+
+export const version = getVersion;
+
+// Default export
+export default {
+  initialize,
+  minify,
+  isInitialized,
+  version: getVersion
+};