@openfluke/welvet 0.2.0 → 0.3.0

package/README.md

@@ -1,8 +1,11 @@
 # @openfluke/welvet - LOOM TypeScript/WASM Bindings
+ 
+ **Wrapper for Embedding Loom Via External (WASM) Toolchain**
+ 
+ High-performance neural network library with **full training in browser/Node.js** via WebAssembly. Zero external dependencies—just import and go.
+ 
+ > **v0.3.0 Update**: Now includes a **Universal Test Suite** (2298 tests) with 100% parity across Browser and Node.js environments.
 
-**Wrapper for Embedding Loom Via External (WASM) Toolchain**
-
-High-performance neural network library with **full training in browser/Node.js** via WebAssembly. Zero external dependencies—just import and go.
 
 ## Framework Comparison
 
@@ -217,26 +220,34 @@ Tests **5 architectures × 3 depths × 5 training modes** (75 tests total):
 - **Modes:** NormalBP, StepBP, Tween, TweenChain, StepTweenChain
 
 ## Complete Test Suite
-
-The `universal_test.ts` example demonstrates all framework capabilities:
-
-```bash
-cd example
-bun run universal_test.ts
-```
-
-**Test Coverage:**
-- ✅ 12 Layer Types × 6 Data Types (72 tests)
-- ✅ Network Grafting
-- ✅ K-Means Clustering & Correlation Analysis
-- ✅ Optimizers (SGD, AdamW, RMSprop)
-- ✅ Ensemble Features
-- ✅ Observer Pattern (Adaptation Tracking)
-- ✅ Introspection API
-- ✅ Step & Tween API
-- ✅ Advanced Layers (Embedding, Residual)
-
-See [`example/universal_test.ts`](./example/universal_test.ts) for the complete test implementation.
+ 
+ The `universal_test.ts` example demonstrates all framework capabilities with **100% parity** to the Go/C core.
+ 
+ ### Running in Browser (v0.3.0+)
+ 
+ The universal test suite now runs directly in the browser with a full DOM report:
+ 
+ ```bash
+ cd typescript
+ python3 serve.py
+ # Open http://localhost:8081
+ ```
+ 
+ ### Running in Node/Bun
+ 
+ ```bash
+ cd example
+ bun run universal_test.ts
+ ```
+ 
+ **Test Coverage (2298 Tests):**
+ - ✅ **Serialization**: 12 Layer Types × 15 Data Types (2100 combinations)
+ - ✅ **In-Memory WASM**: SafeTensors without filesystem (144 tests)
+ - ✅ **Advanced Math**: K-Means, Correlation, Grafting, Ensembles
+ - ✅ **GPU Parity**: Determinism checks for forward/backward passes
+ - ✅ **Core**: Architecture generation, combinators, sequential layers
+ 
+ See [`example/universal_test.ts`](./example/universal_test.ts) for the complete test implementation.
 
 ## Layer Types
 

package/dist/index.d.ts

@@ -5,23 +5,28 @@
  * Provides the same API in both Node.js and browser environments.
  */
 import { Network, GraftResult, KMeansResult, CorrelationResult, EnsembleMatch, AdaptationTracker } from "./types.js";
-import { loadLoomWASM } from "./loader.js";
 import { loadLoomWASMBrowser } from "./loader.browser.js";
 export * from "./types.js";
-export { loadLoomWASM, loadLoomWASMBrowser };
+export { loadLoomWASMBrowser };
+export declare function loadLoomWASM(): Promise<void>;
 /**
- * Initialize WASM for Node.js environment
+ * Initialize WASM
+ * Auto-detects environment (Browser vs Node.js)
  */
-export declare function init(): Promise<void>;
+export declare function init(wasmUrl?: string): Promise<void>;
 /**
  * Initialize WASM for Browser environment
  */
-export declare function initBrowser(): Promise<void>;
+export declare function initBrowser(wasmUrl?: string): Promise<void>;
 /**
  * Create a network from JSON config
  * Wrapper around the global createLoomNetwork function exposed by WASM
  */
 export declare function createNetwork(config: object | string): Network;
+/**
+ * Load a network from JSON string and ID
+ */
+export declare function loadNetwork(jsonString: string, modelID: string): Network;
 /**
  * Create a network handle for grafting
  */
@@ -53,6 +58,7 @@ declare const _default: {
     init: typeof init;
     initBrowser: typeof initBrowser;
     createNetwork: typeof createNetwork;
+    loadNetwork: typeof loadNetwork;
     createKHandle: typeof createKHandle;
     graft: typeof graft;
     kmeans: typeof kmeans;

package/dist/index.js

@@ -4,21 +4,29 @@
  * Direct wrapper around Loom WASM that mirrors main.go exports exactly.
  * Provides the same API in both Node.js and browser environments.
  */
-import { loadLoomWASM } from "./loader.js";
 import { loadLoomWASMBrowser } from "./loader.browser.js";
 export * from "./types.js";
-export { loadLoomWASM, loadLoomWASMBrowser };
+export { loadLoomWASMBrowser };
+export async function loadLoomWASM() {
+    const mod = await import("./loader.js");
+    await mod.loadLoomWASM();
+}
 /**
- * Initialize WASM for Node.js environment
+ * Initialize WASM
+ * Auto-detects environment (Browser vs Node.js)
  */
-export async function init() {
-    await loadLoomWASM();
+export async function init(wasmUrl) {
+    // Check for browser environment (needs window and document for loader.browser.ts)
+    if (typeof window !== "undefined" && typeof document !== "undefined") {
+        return initBrowser(wasmUrl);
+    }
+    return loadLoomWASM();
 }
 /**
  * Initialize WASM for Browser environment
  */
-export async function initBrowser() {
-    await loadLoomWASMBrowser();
+export async function initBrowser(wasmUrl) {
+    await loadLoomWASMBrowser(wasmUrl);
 }
 /**
  * Create a network from JSON config
@@ -30,6 +38,12 @@ export function createNetwork(config) {
         : JSON.stringify(config);
     return createLoomNetwork(jsonConfig);
 }
+/**
+ * Load a network from JSON string and ID
+ */
+export function loadNetwork(jsonString, modelID) {
+    return loadLoomNetwork(jsonString, modelID);
+}
 /**
  * Create a network handle for grafting
  */
@@ -86,6 +100,7 @@ export default {
     init,
     initBrowser,
     createNetwork,
+    loadNetwork,
     createKHandle,
     graft,
     kmeans,

package/dist/loader.browser.d.ts

@@ -2,4 +2,4 @@
  * LOOM WASM Browser Loader
  * Browser-only version without Node.js dependencies
  */
-export declare function loadLoomWASMBrowser(): Promise<void>;
+export declare function loadLoomWASMBrowser(wasmUrl?: string): Promise<void>;

package/dist/loader.browser.js

@@ -2,7 +2,7 @@
  * LOOM WASM Browser Loader
  * Browser-only version without Node.js dependencies
  */
-export async function loadLoomWASMBrowser() {
+export async function loadLoomWASMBrowser(wasmUrl) {
     // For browser environments - load wasm_exec.js first if not already loaded
     if (typeof globalThis.Go === "undefined") {
         // Load wasm_exec.js dynamically from /dist/
@@ -14,7 +14,7 @@ export async function loadLoomWASMBrowser() {
             document.head.appendChild(script);
         });
     }
-    const response = await fetch("/dist/main.wasm");
+    const response = await fetch(wasmUrl || "/dist/main.wasm");
     const wasmBuffer = await response.arrayBuffer();
     // @ts-ignore - Go is defined by wasm_exec.js
     const go = new Go();

package/dist/loader.js

@@ -2,12 +2,13 @@
  * LOOM WASM Loader
  * Loads and initializes the LOOM WebAssembly module (Node.js only)
  */
-import { readFileSync } from "fs";
-import { fileURLToPath } from "url";
-import { dirname, join } from "path";
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+// Node.js only loader - using dynamic imports to allow bundling for browser (where this file is not used but might be analyzed)
 export async function loadLoomWASM() {
+    const fs = await import("fs");
+    const url = await import("url");
+    const path = await import("path");
+    const __filename = url.fileURLToPath(import.meta.url);
+    const __dirname = path.dirname(__filename);
     // __dirname points to:
     // - dist/   → in production
     // - src/    → when running via Bun, ts-node, or example files
@@ -19,16 +20,16 @@ export async function loadLoomWASM() {
     else {
         // Running from src/ or example/
         // Point to project’s dist/ directory
-        root = join(__dirname, "..", "dist");
+        root = path.join(__dirname, "..", "dist");
     }
     // Load wasm_exec.js
-    const wasmExecPath = join(root, "wasm_exec.js");
-    const wasmExecCode = readFileSync(wasmExecPath, "utf-8");
+    const wasmExecPath = path.join(root, "wasm_exec.js");
+    const wasmExecCode = fs.readFileSync(wasmExecPath, "utf-8");
     // Execute wasm_exec.js to get the Go runtime
     eval(wasmExecCode);
     // Load main.wasm
-    const wasmPath = join(root, "main.wasm");
-    const wasmBuffer = readFileSync(wasmPath);
+    const wasmPath = path.join(root, "main.wasm");
+    const wasmBuffer = fs.readFileSync(wasmPath);
     // @ts-ignore - Go runtime from wasm_exec.js
     const go = new Go();
     const { instance } = await WebAssembly.instantiate(wasmBuffer, go.importObject);

package/dist/types.d.ts

@@ -157,6 +157,7 @@ export interface TweenState {
  */
 declare global {
     function createLoomNetwork(jsonConfig: string): Network;
+    function loadLoomNetwork(jsonString: string, modelID: string): Network;
     function createAdaptationTracker(windowMs: number, totalMs: number): AdaptationTracker;
     function createNetworkForGraft(jsonConfig: string): number;
     function graftNetworks(idsJSON: string, combineMode: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfluke/welvet",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "TypeScript/JavaScript bindings for LOOM neural network framework with WebAssembly support - GPU-accelerated machine learning in the browser",
   "type": "module",
   "main": "./dist/index.js",