miniray 0.1.3 → 0.2.0

package/README.md

@@ -60,7 +60,7 @@ console.log(result.code);
 
 ### `initialize(options)`
 
-Initialize the WASM module. Must be called before `minify()`.
+Initialize the WASM module. Must be called before `minify()` or `reflect()`.
 
 ```typescript
 interface InitializeOptions {
@@ -95,6 +95,81 @@ interface MinifyResult {
 }
 ```
 
+### `reflect(source)`
+
+Extract binding information, struct layouts, and entry points from WGSL source.
+
+```typescript
+interface ReflectResult {
+  bindings: BindingInfo[];
+  structs: Record<string, StructLayout>;
+  entryPoints: EntryPointInfo[];
+  errors: string[];
+}
+
+interface BindingInfo {
+  group: number;
+  binding: number;
+  name: string;
+  addressSpace: string;    // "uniform", "storage", "handle"
+  accessMode?: string;     // "read", "write", "read_write" (for storage)
+  type: string;
+  layout: StructLayout | null;  // null for textures/samplers
+}
+
+interface StructLayout {
+  size: number;
+  alignment: number;
+  fields: FieldInfo[];
+}
+
+interface FieldInfo {
+  name: string;
+  type: string;
+  offset: number;
+  size: number;
+  alignment: number;
+  layout?: StructLayout;   // for nested structs
+}
+
+interface EntryPointInfo {
+  name: string;
+  stage: string;           // "vertex", "fragment", "compute"
+  workgroupSize: number[] | null;  // [x, y, z] for compute, null otherwise
+}
+```
+
+**Example:**
+
+```javascript
+const result = reflect(`
+  struct Uniforms { time: f32, resolution: vec2<u32> }
+  @group(0) @binding(0) var<uniform> u: Uniforms;
+  @compute @workgroup_size(8, 8) fn main() {}
+`);
+
+console.log(result.bindings[0]);
+// {
+//   group: 0, binding: 0, name: "u",
+//   addressSpace: "uniform", type: "Uniforms",
+//   layout: {
+//     size: 16, alignment: 8,
+//     fields: [
+//       { name: "time", type: "f32", offset: 0, size: 4, alignment: 4 },
+//       { name: "resolution", type: "vec2<u32>", offset: 8, size: 8, alignment: 8 }
+//     ]
+//   }
+// }
+
+console.log(result.entryPoints[0]);
+// { name: "main", stage: "compute", workgroupSize: [8, 8, 1] }
+```
+
+Memory layouts follow the WGSL specification:
+- `vec3` has alignment=16 but size=12
+- Struct members are aligned to their natural alignment
+- Struct size is rounded up to struct alignment
+
 ### `isInitialized()`
 
 Returns `true` if the WASM module is initialized.

package/esm/node.mjs

@@ -40,8 +40,15 @@ export async function initialize(options) {
   const wasmModule = options.wasmModule;
 
   // Default to miniray.wasm in the package directory
+  // Use require.resolve to find files within the package, which works
+  // regardless of bundling or working directory
   if (!wasmURL && !wasmModule) {
-    wasmURL = path.join(__dirname, '..', 'miniray.wasm');
+    try {
+      wasmURL = require.resolve('miniray/miniray.wasm');
+    } catch {
+      // Fallback to relative path for local development
+      wasmURL = path.join(__dirname, '..', 'miniray.wasm');
+    }
   }
 
   _initPromise = _doInitialize(wasmURL, wasmModule);
@@ -57,7 +64,16 @@ export async function initialize(options) {
 
 async function _doInitialize(wasmURL, wasmModule) {
   // Load wasm_exec.js - this defines Go globally
-  const wasmExecPath = path.join(__dirname, '..', 'wasm_exec.js');
+  // Use require.resolve to find files within the package, which works
+  // regardless of bundling or working directory
+  let wasmExecPath;
+  try {
+    wasmExecPath = require.resolve('miniray/wasm_exec.js');
+  } catch {
+    // Fallback to relative path for local development
+    wasmExecPath = path.join(__dirname, '..', 'wasm_exec.js');
+  }
+
   if (!fs.existsSync(wasmExecPath)) {
     throw new Error(`wasm_exec.js not found at ${wasmExecPath}`);
   }
@@ -122,6 +138,23 @@ export function minify(source, options) {
   return globalThis.__miniray.minify(source, options || {});
 }
 
+/**
+ * Reflect WGSL source to extract binding and struct information.
+ * @param {string} source - WGSL source code
+ * @returns {Object} Reflection result with bindings, structs, entryPoints, and errors
+ */
+export function reflect(source) {
+  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.reflect(source);
+}
+
 /**
  * Check if initialized.
  * @returns {boolean}
@@ -147,6 +180,7 @@ export const version = getVersion;
 export default {
   initialize,
   minify,
+  reflect,
   isInitialized,
   version: getVersion
 };

package/lib/browser.js

@@ -149,6 +149,23 @@
     return globalThis.__miniray.minify(source, options || {});
   }
 
+  /**
+   * Reflect WGSL source to extract binding and struct information.
+   * @param {string} source - WGSL source code
+   * @returns {Object} Reflection result with bindings, structs, entryPoints, and errors
+   */
+  function reflect(source) {
+    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.reflect(source);
+  }
+
   /**
    * Check if initialized.
    * @returns {boolean}
@@ -171,6 +188,7 @@
   return {
     initialize: initialize,
     minify: minify,
+    reflect: reflect,
     isInitialized: isInitialized,
     get version() { return getVersion(); }
   };

package/lib/main.d.ts

@@ -75,6 +75,82 @@ export interface MinifyResult {
   minifiedSize: number;
 }
 
+/**
+ * Result of shader reflection.
+ */
+export interface ReflectResult {
+  /** Binding declarations (@group/@binding variables) */
+  bindings: BindingInfo[];
+  /** Struct type layouts */
+  structs: Record<string, StructLayout>;
+  /** Entry point functions */
+  entryPoints: EntryPointInfo[];
+  /** Parse errors, if any */
+  errors: string[];
+}
+
+/**
+ * Information about a binding variable.
+ */
+export interface BindingInfo {
+  /** Binding group index from @group(n) */
+  group: number;
+  /** Binding index from @binding(n) */
+  binding: number;
+  /** Variable name */
+  name: string;
+  /** Address space: "uniform", "storage", "handle", or "" */
+  addressSpace: string;
+  /** Access mode for storage: "read", "write", "read_write", or undefined */
+  accessMode?: string;
+  /** Type as a string (e.g., "MyStruct", "texture_2d<f32>") */
+  type: string;
+  /** Memory layout for struct types, null for textures/samplers */
+  layout: StructLayout | null;
+}
+
+/**
+ * Memory layout of a struct type.
+ */
+export interface StructLayout {
+  /** Total size in bytes */
+  size: number;
+  /** Required alignment in bytes */
+  alignment: number;
+  /** Field layouts */
+  fields: FieldInfo[];
+}
+
+/**
+ * Layout information for a struct field.
+ */
+export interface FieldInfo {
+  /** Field name */
+  name: string;
+  /** Field type as a string */
+  type: string;
+  /** Byte offset from start of struct */
+  offset: number;
+  /** Size in bytes */
+  size: number;
+  /** Required alignment in bytes */
+  alignment: number;
+  /** Nested layout for struct or array-of-struct fields */
+  layout?: StructLayout;
+}
+
+/**
+ * Information about a shader entry point.
+ */
+export interface EntryPointInfo {
+  /** Function name */
+  name: string;
+  /** Shader stage: "vertex", "fragment", or "compute" */
+  stage: string;
+  /** Workgroup size [x, y, z] for compute, null otherwise */
+  workgroupSize: [number, number, number] | null;
+}
+
 /**
  * Options for initializing the WASM module.
  */
@@ -106,6 +182,13 @@ export function initialize(options: InitializeOptions): Promise<void>;
  */
 export function minify(source: string, options?: MinifyOptions): MinifyResult;
 
+/**
+ * Reflect WGSL source to extract binding and struct information.
+ * @param source - WGSL source code to analyze
+ * @returns Reflection result with bindings, structs, entryPoints, and errors
+ */
+export function reflect(source: string): ReflectResult;
+
 /**
  * Check if the WASM module is initialized.
  */

package/lib/main.js

@@ -36,8 +36,15 @@ async function initialize(options) {
   const wasmModule = options.wasmModule;
 
   // Default to miniray.wasm in the package directory
+  // Use require.resolve to find files within the package, which works
+  // regardless of bundling or working directory
   if (!wasmURL && !wasmModule) {
-    wasmURL = path.join(__dirname, '..', 'miniray.wasm');
+    try {
+      wasmURL = require.resolve('miniray/miniray.wasm');
+    } catch {
+      // Fallback to relative path for local development
+      wasmURL = path.join(__dirname, '..', 'miniray.wasm');
+    }
   }
 
   _initPromise = _doInitialize(wasmURL, wasmModule);
@@ -62,7 +69,16 @@ async function _doInitialize(wasmURL, wasmModule) {
   globalThis.crypto ??= require('crypto');
 
   // Load wasm_exec.js to set up Go runtime
-  const wasmExecPath = path.join(__dirname, '..', 'wasm_exec.js');
+  // Use require.resolve to find files within the package, which works
+  // regardless of bundling or working directory
+  let wasmExecPath;
+  try {
+    wasmExecPath = require.resolve('miniray/wasm_exec.js');
+  } catch {
+    // Fallback to relative path for local development
+    wasmExecPath = path.join(__dirname, '..', 'wasm_exec.js');
+  }
+
   if (!fs.existsSync(wasmExecPath)) {
     throw new Error(`wasm_exec.js not found at ${wasmExecPath}`);
   }
@@ -125,6 +141,23 @@ function minify(source, options) {
   return global.__miniray.minify(source, options || {});
 }
 
+/**
+ * Reflect WGSL source to extract binding and struct information.
+ * @param {string} source - WGSL source code
+ * @returns {Object} Reflection result with bindings, structs, entryPoints, and errors
+ */
+function reflect(source) {
+  if (!_initialized) {
+    throw new Error('miniray not initialized. Call initialize() first.');
+  }
+
+  if (typeof source !== 'string') {
+    throw new Error('source must be a string');
+  }
+
+  return global.__miniray.reflect(source);
+}
+
 /**
  * Check if initialized.
  * @returns {boolean}
@@ -147,6 +180,7 @@ function getVersion() {
 module.exports = {
   initialize,
   minify,
+  reflect,
   isInitialized,
   get version() { return getVersion(); }
 };

package/package.json

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