@gasm-compiler/core 0.2.1 → 0.3.0

package/README.md

@@ -118,6 +118,17 @@ import { compile } from "@gasm-compiler/core/browser";
 const wgslCode = compile(wasmBytes);
 ```
 
+The compiler has no required browser initialization step. For applications that
+want to fetch and cache the Wasm compiler ahead of time, the browser entry point
+also exposes an optional async path:
+
+```typescript
+import { compileAsync, preloadCompiler } from "@gasm-compiler/core/browser";
+
+await preloadCompiler();
+const wgslCode = await compileAsync(wasmBytes);
+```
+
 ### Using with WebGPU
 
 ```typescript
@@ -229,6 +240,47 @@ Compiles a WebAssembly binary to WGSL.
 
 **Throws:** `CompileError` on validation or compilation failure
 
+### `compileAsync(source, options?)`
+
+```typescript
+function compileAsync(source: Uint8Array, options?: CompileOptions): Promise<string>
+```
+
+Async equivalent of `compile`. In browsers this can be paired with
+`preloadCompiler()` to fetch and instantiate the compiler artifact before the
+first compilation.
+
+### `compileWithDiagnostics(source, options?)`
+
+```typescript
+function compileWithDiagnostics(
+  source: Uint8Array,
+  options?: CompileOptions,
+): CompileWithDiagnosticsResult
+```
+
+Compiles a WebAssembly binary and returns diagnostics instead of throwing.
+
+### `compileWithDiagnosticsAsync(source, options?)`
+
+```typescript
+function compileWithDiagnosticsAsync(
+  source: Uint8Array,
+  options?: CompileOptions,
+): Promise<CompileWithDiagnosticsResult>
+```
+
+Async equivalent of `compileWithDiagnostics`.
+
+### `preloadCompiler(options?)`
+
+```typescript
+function preloadCompiler(options?: { wasmUrl?: string | URL }): Promise<void>
+```
+
+Optional performance hook for browser applications that want to load the
+compiler before the first call to `compileAsync`.
+
 ### `CompileOptions`
 
 ```typescript

package/dist/browser-executor.js

@@ -1 +1 @@
-import{a}from"./chunk-G6YRZSKB.js";import"./chunk-STDXBN5E.js";export{a as BrowserGPUExecutor};
+import{a}from"./chunk-IZGS3OS2.js";import"./chunk-STDXBN5E.js";export{a as BrowserGPUExecutor};

package/dist/browser.d.ts

@@ -1,10 +1,63 @@
-import { C as CompileDiagnostics, D as DispatchInfo, a as CompileOptions } from './parser-C7xAx4nx.js';
-export { b as CompileError, m as isCompileError, o as isParseError, r as parseWasmModule } from './parser-C7xAx4nx.js';
+import { C as CompileDiagnostics, D as DispatchInfo$1, a as CompileOptions } from './error_codes-D6RsiZ33.js';
+export { b as CompileError, h as ErrorCode, E as ErrorCodes, c as SPEC_VERSION_V01, d as SPEC_VERSION_V02, S as SpecVersion, e as isCompileError, g as isParseError, i as isV02Mode, f as parseWasmModule, r as resolveSpecVersion } from './error_codes-D6RsiZ33.js';
 export { BrowserGPUExecutor } from './browser-executor.js';
 export { BufferData, ExecuteOptions, ExecutionError, ExecutorConfig, IGPUExecutor, OutputBufferSpec, isExecutionError } from './executor.js';
 
+type BrowserTsCompileWithDiagnosticsResult = {
+    ok: true;
+    wgsl: string;
+    diagnostics: CompileDiagnostics;
+    dispatchInfo: DispatchInfo$1;
+} | {
+    ok: false;
+    diagnostics: CompileDiagnostics;
+};
+
+interface InitRustCompilerOptions {
+    wasmUrl?: string | URL;
+}
+declare function preloadCompiler(options?: InitRustCompilerOptions): Promise<void>;
+declare const initRustCompiler: typeof preloadCompiler;
+declare function isRustCompilerInitialized(): boolean;
+declare function waitForRustCompilerInit(): Promise<void>;
+
+/**
+ * Shared helpers for comparing TypeScript and Rust/Wasm WGSL output.
+ */
+interface WgslDiffOptions {
+    /** Maximum diff hunk lines to include in formatted output. */
+    maxLines?: number;
+    /** Lines of context around each change hunk. */
+    context?: number;
+}
+interface WgslComparisonSummary {
+    equivalent: boolean;
+    moduleEquivalent: boolean;
+    functionEquivalent?: boolean;
+    moduleDiff?: string;
+    functionDiff?: string;
+    typescriptSnippet?: string;
+    rustSnippet?: string;
+}
+declare function normalizeWgslForComparison(wgsl: string): string;
+declare function exportWgslFunctionSnippet(wgsl: string, funcName: string): string | null;
+declare function summarizeWgslComparison(typescriptWgsl: string, rustWgsl: string, funcName?: string, options?: WgslDiffOptions): WgslComparisonSummary;
+declare function formatUnifiedDiff(leftLabel: string, rightLabel: string, left: string, right: string, options?: WgslDiffOptions): string;
+
+type BrowserCompilerBackend = "typescript" | "rust" | "compare";
+declare function setBrowserCompilerBackend(backend: BrowserCompilerBackend): void;
+declare function getBrowserCompilerBackend(): BrowserCompilerBackend;
 declare function disassembleToWAT(wasmBytes: Uint8Array): Promise<string>;
 
+interface DispatchInfo {
+    workItemsX: number;
+    workItemsY: number;
+    workItemsZ: number;
+    workgroupSizeX: number;
+    workgroupSizeY: number;
+    workgroupSizeZ: number;
+    isParallelized: boolean;
+}
 type CompileWithDiagnosticsResult = {
     ok: true;
     wgsl: string;
@@ -14,7 +67,35 @@ type CompileWithDiagnosticsResult = {
     ok: false;
     diagnostics: CompileDiagnostics;
 };
+interface BackendMismatchDetails {
+    kind: "wgsl" | "ok_mismatch" | "rust_error" | "diagnostics";
+    message: string;
+    moduleDiff?: string;
+    functionDiff?: string;
+    typescriptWgsl?: string;
+    rustWgsl?: string;
+}
+interface BackendComparisonResult {
+    selectedBackend: "typescript";
+    returned: CompileWithDiagnosticsResult;
+    typescript: BrowserTsCompileWithDiagnosticsResult;
+    rust: CompileWithDiagnosticsResult | {
+        ok: false;
+        error: string;
+    };
+    equivalent: boolean;
+    mismatch?: BackendMismatchDetails;
+}
+
 declare function compileWithDiagnostics(wasmBytes: Uint8Array, options?: CompileOptions): CompileWithDiagnosticsResult;
+declare function compileWithDiagnosticsAsync(wasmBytes: Uint8Array, options?: CompileOptions, initOptions?: InitRustCompilerOptions): Promise<CompileWithDiagnosticsResult>;
+declare function compileWithBackendComparison(wasmBytes: Uint8Array, options?: CompileOptions, compareOptions?: {
+    funcName?: string;
+}): BackendComparisonResult;
+declare function compileWithBackendComparisonAsync(wasmBytes: Uint8Array, options?: CompileOptions, compareOptions?: {
+    funcName?: string;
+}, initOptions?: InitRustCompilerOptions): Promise<BackendComparisonResult>;
 declare function compile(wasmBytes: Uint8Array, options?: CompileOptions): string;
+declare function compileAsync(wasmBytes: Uint8Array, options?: CompileOptions, initOptions?: InitRustCompilerOptions): Promise<string>;
 
-export { CompileDiagnostics, CompileOptions, type CompileWithDiagnosticsResult, DispatchInfo, compile, compileWithDiagnostics, disassembleToWAT };
+export { type BackendComparisonResult, type BackendMismatchDetails, type BrowserCompilerBackend, CompileDiagnostics, CompileOptions, type CompileWithDiagnosticsResult, type DispatchInfo, type InitRustCompilerOptions, type WgslComparisonSummary, type WgslDiffOptions, compile, compileAsync, compileWithBackendComparison, compileWithBackendComparisonAsync, compileWithDiagnostics, compileWithDiagnosticsAsync, disassembleToWAT, exportWgslFunctionSnippet, formatUnifiedDiff, getBrowserCompilerBackend, initRustCompiler, isRustCompilerInitialized, normalizeWgslForComparison, preloadCompiler, setBrowserCompilerBackend, summarizeWgslComparison, waitForRustCompilerInit };