@gasm-compiler/core 0.4.0 → 0.6.0

package/README.md

@@ -15,7 +15,8 @@ Gasm v0.1 behavior remains available through an explicit compatibility option.
 npm install @gasm-compiler/core
 ```
 
-**Requirements:** TypeScript 5.0+ (peer dependency)
+The compiler core is distributed as a Rust-generated WebAssembly artifact. No
+TypeScript runtime dependency is required by consumers.
 
 ---
 
@@ -85,10 +86,12 @@ const schema = validateGasmMetadataSchema(result.metadata);
 if (!schema.valid) throw new Error(schema.errors.join(", "));
 ```
 
-Gasm v0.2 semantics are implemented only in `packages/core-rs` and distributed
-through its Wasm artifact. The TypeScript compiler implementation is retained
-at v0.1 for compatibility. Deno remains the runtime for the CLI and the live
-core/CLI test suites, including headless WebGPU execution.
+All Gasm compiler semantics, including explicit v0.1 compatibility mode, are
+implemented in `packages/core-rs` and distributed through its Wasm artifact.
+The TypeScript package code is limited to host integration, artifact metadata,
+source-map comments, preparation helpers, and execution APIs. Deno remains the
+runtime for the CLI and the live core/CLI test suites, including headless
+WebGPU execution.
 
 The CLI also defaults to v0.2:
 
@@ -100,6 +103,22 @@ gasm-compiler compile input.wasm \
 
 Use `--spec-version 0.1` when compiling archived v0.1 inputs.
 
+#### Migrating from 0.5.x
+
+- The Rust/Wasm compiler is now the only compiler backend. The
+  `GASM_CORE_BACKEND` environment variable no longer changes compilation.
+- Browser backend selection APIs have been removed:
+  `setBrowserCompilerBackend()`, `getBrowserCompilerBackend()`, and
+  `BrowserCompilerBackend`.
+- TypeScript/Rust comparison APIs and their result types have been removed:
+  `compileWithBackendComparison()`, `compileWithBackendComparisonAsync()`,
+  `BackendComparisonResult`, and `BackendMismatchDetails`.
+- Remove backend-selection and comparison UI from integrator applications and
+  call `compile()`, `compileWithDiagnostics()`, or
+  `compileWithDiagnosticsAsync()` directly.
+- Consumers no longer need to install TypeScript as a peer dependency of
+  `@gasm-compiler/core`.
+
 #### Migrating from 0.3.x
 
 - Compilation now defaults to strict Gasm v0.2 validation.
@@ -113,6 +132,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,18 +1,8 @@
-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, 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';
 
-type BrowserTsCompileWithDiagnosticsResult = {
-    ok: true;
-    wgsl: string;
-    diagnostics: CompileDiagnostics;
-    dispatchInfo: DispatchInfo$1;
-} | {
-    ok: false;
-    diagnostics: CompileDiagnostics;
-};
-
 interface InitRustCompilerOptions {
     wasmUrl?: string | URL;
 }
@@ -21,32 +11,6 @@ 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 {
@@ -67,35 +31,33 @@ 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;
-}
-
+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;
+};
 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;
-}): 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 { 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 CompileArtifactResult, CompileDiagnostics, CompileOptions, type CompileWithDiagnosticsResult, type CompileWithRuntimeInfoResult, type DispatchInfo, GasmBinding, GasmMetadata, type InitRustCompilerOptions, PrepareModuleOptions, PreparedModule, compile, compileAsync, compileToArtifact, compileWithDiagnostics, compileWithDiagnosticsAsync, compileWithRuntimeInfo, disassembleToWAT, initRustCompiler, isRustCompilerInitialized, preloadCompiler, waitForRustCompilerInit };