@gasm-compiler/core 0.4.0 → 0.5.0

package/README.md

@@ -113,6 +113,44 @@ Required extensions are declared by the module's `gasm.extensions` custom
 section. The CLI does not inject extensions, so validation reflects the exact
 module that will be distributed.
 
+### Integrator Workflow
+
+Playgrounds, compiler backends, and other embedders can prepare transient Wasm
+without modifying their producer toolchain:
+
+```typescript
+import {
+  compileWithRuntimeInfo,
+  prepareModule,
+} from "@gasm-compiler/core/browser";
+
+const prepared = prepareModule(wasmBytes, {
+  demotionPolicy: { f64: "allow", i64: "allow-lossy" },
+});
+if (prepared.errors.length > 0) {
+  throw new Error(prepared.errors[0].message);
+}
+
+const result = compileWithRuntimeInfo(prepared.wasmBytes, {
+  ...prepared.compileOptions,
+  mode: "strict",
+});
+if (!result.ok) throw new Error(result.diagnostics.errors[0].message);
+```
+
+`prepareModule()` defaults to integrator mode. It infers required extensions,
+merges a stable `gasm.extensions` section, and returns binding and mutable-global
+initialization data. Modules with undeclared mutable defined globals use the
+v0.1 private-global compatibility path to avoid shared-storage races.
+
+Use `{ mode: "strict" }` to analyze a distribution artifact without changing
+its bytes. Strict compilation through `compile()` and
+`compileWithDiagnostics()` remains unchanged and never injects extensions.
+
+`compileWithRuntimeInfo()` is also available from the main and browser entry
+points. It combines preparation, compilation, binding metadata, dispatch
+information, and mutable-global initialization into one result.
+
 ### Basic Compilation
 
 ```typescript

package/dist/browser.d.ts

@@ -1,5 +1,5 @@
-import { a as CompileDiagnostics, D as DispatchInfo$1, C as CompileOptions } from './error_codes-Cdy_3FNo.js';
-export { b as CompileError, c as DEFAULT_SPEC_VERSION, j as ErrorCode, E as ErrorCodes, d as SPEC_VERSION_V01, e as SPEC_VERSION_V02, S as SpecVersion, f as isCompileError, h as isParseError, i as isV02Mode, g as parseWasmModule, r as resolveSpecVersion } from './error_codes-Cdy_3FNo.js';
+import { C as CompileDiagnostics, D as DispatchInfo$1, G as GasmMetadata, a as GasmBinding, P as PreparedModule, b as CompileOptions, c as PrepareModuleOptions } from './error_codes-5zCZDwFZ.js';
+export { d as CompileError, h as DEFAULT_SPEC_VERSION, e as DemotionPolicy, f as Diagnostic, g as DiagnosticRecovery, o as ErrorCode, E as ErrorCodes, u as GasmMetadataEntryPoint, M as MutableGlobalsInit, x as PrepareMode, j as SPEC_VERSION_V01, k as SPEC_VERSION_V02, S as SpecVersion, w as buildBindingTable, s as buildGasmMetadata, l as isCompileError, n as isParseError, i as isV02Mode, m as parseWasmModule, p as prepareModule, r as resolveSpecVersion, v as validateGasmMetadataSchema } from './error_codes-5zCZDwFZ.js';
 export { BrowserGPUExecutor } from './browser-executor.js';
 export { BufferData, ExecuteOptions, ExecutionError, ExecutorConfig, IGPUExecutor, OutputBufferSpec, isExecutionError } from './executor.js';
 
@@ -67,6 +67,28 @@ type CompileWithDiagnosticsResult = {
     ok: false;
     diagnostics: CompileDiagnostics;
 };
+type CompileArtifactResult = {
+    ok: true;
+    wgsl: string;
+    metadata: GasmMetadata;
+    diagnostics: CompileDiagnostics;
+    dispatchInfo: DispatchInfo;
+} | {
+    ok: false;
+    diagnostics: CompileDiagnostics;
+};
+type CompileWithRuntimeInfoResult = {
+    ok: true;
+    wgsl: string;
+    diagnostics: CompileDiagnostics;
+    dispatchInfo: DispatchInfo;
+    bindings: GasmBinding[];
+    metadata: GasmMetadata;
+    mutableGlobalsInit?: PreparedModule["mutableGlobalsInit"];
+} | {
+    ok: false;
+    diagnostics: CompileDiagnostics;
+};
 interface BackendMismatchDetails {
     kind: "wgsl" | "ok_mismatch" | "rust_error" | "diagnostics";
     message: string;
@@ -88,6 +110,8 @@ interface BackendComparisonResult {
 }
 
 declare function compileWithDiagnostics(wasmBytes: Uint8Array, options?: CompileOptions): CompileWithDiagnosticsResult;
+declare function compileToArtifact(wasmBytes: Uint8Array, options?: CompileOptions): CompileArtifactResult;
+declare function compileWithRuntimeInfo(wasmBytes: Uint8Array, options?: PrepareModuleOptions): CompileWithRuntimeInfoResult;
 declare function compileWithDiagnosticsAsync(wasmBytes: Uint8Array, options?: CompileOptions, initOptions?: InitRustCompilerOptions): Promise<CompileWithDiagnosticsResult>;
 declare function compileWithBackendComparison(wasmBytes: Uint8Array, options?: CompileOptions, compareOptions?: {
     funcName?: string;
@@ -98,4 +122,4 @@ declare function compileWithBackendComparisonAsync(wasmBytes: Uint8Array, option
 declare function compile(wasmBytes: Uint8Array, options?: CompileOptions): string;
 declare function compileAsync(wasmBytes: Uint8Array, options?: CompileOptions, initOptions?: InitRustCompilerOptions): Promise<string>;
 
-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 };
+export { type BackendComparisonResult, type BackendMismatchDetails, type BrowserCompilerBackend, type CompileArtifactResult, CompileDiagnostics, CompileOptions, type CompileWithDiagnosticsResult, type CompileWithRuntimeInfoResult, type DispatchInfo, GasmBinding, GasmMetadata, type InitRustCompilerOptions, PrepareModuleOptions, PreparedModule, type WgslComparisonSummary, type WgslDiffOptions, compile, compileAsync, compileToArtifact, compileWithBackendComparison, compileWithBackendComparisonAsync, compileWithDiagnostics, compileWithDiagnosticsAsync, compileWithRuntimeInfo, disassembleToWAT, exportWgslFunctionSnippet, formatUnifiedDiff, getBrowserCompilerBackend, initRustCompiler, isRustCompilerInitialized, normalizeWgslForComparison, preloadCompiler, setBrowserCompilerBackend, summarizeWgslComparison, waitForRustCompilerInit };