wasmcart 0.2.0

package/src/abi.js

@@ -0,0 +1,94 @@
+// wasmcart ABI v3 definitions (backward compatible with v1 and v2)
+
+export const ABI_VERSION = 3;
+export const MIN_ABI_VERSION = 1; // oldest version we still support
+
+// Button bitmask positions (matches common gamepad layout)
+export const BUTTON = {
+  A:       1 << 0,
+  B:       1 << 1,
+  X:       1 << 2,
+  Y:       1 << 3,
+  L:       1 << 4,
+  R:       1 << 5,
+  START:   1 << 6,
+  SELECT:  1 << 7,
+  UP:      1 << 8,
+  DOWN:    1 << 9,
+  LEFT:    1 << 10,
+  RIGHT:   1 << 11,
+  L3:      1 << 12,
+  R3:      1 << 13,
+};
+
+// WCPad struct layout (16 bytes per pad)
+// u16 buttons
+// i16 left_x, left_y, right_x, right_y
+// u8  left_trigger, right_trigger, connected, _pad
+export const PAD_SIZE = 16;
+export const MAX_PADS = 4;
+export const INPUT_REGION_SIZE = PAD_SIZE * MAX_PADS; // 64 bytes
+
+// WCTime struct layout (20 bytes)
+// f64 time_ms (offset 0)
+// f64 delta_ms (offset 8)
+// u32 frame (offset 16)
+export const TIME_SIZE = 20;
+
+// WCInfo struct field offsets (returned by wc_get_info)
+// All fields are u32
+export const INFO_FIELDS = {
+  VERSION:     0,
+  WIDTH:       4,
+  HEIGHT:      8,
+  FB_PTR:      12,
+  AUDIO_PTR:   16,
+  AUDIO_CAP:   20,  // capacity in stereo frames
+  AUDIO_WRITE: 24,  // cart's write cursor offset (pointer to u32 in cart memory)
+  INPUT_PTR:   28,
+  SAVE_PTR:    32,
+  SAVE_SIZE:   36,
+  TIME_PTR:    40,
+  HOST_INFO_PTR: 44, // pointer to wc_host_info_t (host writes before wc_init)
+};
+export const INFO_STRUCT_SIZE = 48;
+
+// WCHostInfo struct layout (written by host before wc_init)
+// All fields are u32
+export const HOST_INFO_FIELDS = {
+  PREFERRED_WIDTH:  0,
+  PREFERRED_HEIGHT: 4,
+  HOST_FPS:         8,
+  AUDIO_SAMPLE_RATE: 12,
+  FLAGS:            16,
+};
+export const HOST_INFO_SIZE = 20;
+
+// Cart info flags (wc_info_t.flags)
+export const FLAG_AUDIO_F32 = 1 << 0;  // audio ring buffer uses float32
+export const FLAG_NET_WS    = 1 << 1;  // cart wants WebSocket imports
+export const FLAG_NET_DC    = 1 << 2;  // cart wants data channel imports
+export const FLAG_POINTER   = 1 << 3;  // cart wants pointer input
+export const FLAG_KEYBOARD  = 1 << 4;  // cart wants raw keyboard input
+
+// Extended info fields (v3) - byte offsets from wc_info_t start
+export const INFO_FIELDS_V3 = {
+  POINTER_PTR: 56,  // u32 index 14
+  KEYS_PTR:    60,  // u32 index 15
+  GPU_API:     64,  // u32 index 16 - 0=2D, 1=WebGL2/GLES3, 2=WebGPU, 3=Vulkan
+};
+
+// GPU API values for wc_info_t.gpu_api
+export const GPU_API_NONE    = 0;  // 2D framebuffer only
+export const GPU_API_WEBGL2  = 1;  // WebGL2 / GLES3
+export const GPU_API_WEBGPU  = 2;  // reserved
+export const GPU_API_VULKAN  = 3;  // reserved
+
+// Pointer struct layout (8 bytes per pointer)
+// i16 x, i16 y, u8 buttons, u8 active, u8[2] pad
+export const POINTER_SIZE = 8;
+export const MAX_POINTERS = 10;
+export const POINTER_REGION_SIZE = POINTER_SIZE * MAX_POINTERS; // 80 bytes
+
+// Keyboard state bitmask size
+export const KEYS_STATE_SIZE = 32; // 256 bits = 32 bytes

package/src/cartWorker.js

@@ -0,0 +1,201 @@
+/**
+ * cartWorker.js - WASI threads worker entry point
+ *
+ * Runs in a Node.js worker_thread. Receives a compiled WebAssembly.Module
+ * and shared WebAssembly.Memory, instantiates the module, and calls
+ * wasi_thread_start(tid, start_arg).
+ *
+ * All pthread logic (mutexes, condvars, TLS) lives inside the WASM module
+ * via wasi-libc. This worker just provides the host-side imports.
+ */
+
+import { workerData, parentPort } from 'worker_threads';
+import { openSync, readSync, closeSync, statSync } from 'fs';
+import { inflateRawSync } from 'zlib';
+
+const { module: wasmModule, memory, tid, startArg, assetConfig } = workerData;
+
+// --- Asset access (worker opens its own fd for the .wasc file) ---
+
+let assetIndex = null; // Map<path, entry>
+let assetFd = null;
+let assetBuf = null;
+
+if (assetConfig) {
+  if (assetConfig.type === 'zip' && assetConfig.filePath) {
+    assetFd = openSync(assetConfig.filePath, 'r');
+    assetIndex = new Map(assetConfig.index);
+  } else if (assetConfig.type === 'buffer' && assetConfig.buffer) {
+    assetBuf = assetConfig.buffer;
+    assetIndex = new Map(assetConfig.index);
+  } else if (assetConfig.type === 'dir' && assetConfig.dir) {
+    // Directory-based dev mode - not supported in worker yet
+    // (would need readFileSync, rarely used with threaded carts)
+  }
+}
+
+function readZipEntry(fd, entry) {
+  const buf = Buffer.alloc(entry.compressedSize);
+  readSync(fd, buf, 0, entry.compressedSize, entry.dataOffset);
+  if (entry.compressionMethod === 0) return buf;
+  if (entry.compressionMethod === 8) return inflateRawSync(buf);
+  return null;
+}
+
+function readZipEntryFromBuffer(buf, entry) {
+  const data = buf.slice(entry.dataOffset, entry.dataOffset + entry.compressedSize);
+  if (entry.compressionMethod === 0) return data;
+  if (entry.compressionMethod === 8) return inflateRawSync(data);
+  return null;
+}
+
+function assetSize(pathPtr, pathLen) {
+  if (!assetIndex) return -1;
+  const path = new TextDecoder().decode(new Uint8Array(memory.buffer, pathPtr, pathLen));
+  const entry = assetIndex.get(path);
+  return entry ? entry.uncompressedSize : -1;
+}
+
+function loadAsset(pathPtr, pathLen, destPtr, maxSize) {
+  if (!assetIndex) return -1;
+  const path = new TextDecoder().decode(new Uint8Array(memory.buffer, pathPtr, pathLen));
+  const entry = assetIndex.get(path);
+  if (!entry) return -1;
+  if (entry.uncompressedSize > maxSize) return -1;
+
+  let data;
+  if (assetFd !== null) {
+    data = readZipEntry(assetFd, entry);
+  } else if (assetBuf) {
+    data = readZipEntryFromBuffer(assetBuf, entry);
+  } else {
+    return -1;
+  }
+  if (!data) return -1;
+
+  // Write into shared WASM memory
+  const dest = new Uint8Array(memory.buffer, destPtr, data.length);
+  dest.set(new Uint8Array(data.buffer || data, data.byteOffset, data.length));
+  return data.length;
+}
+
+// --- Build import object ---
+
+const imports = {
+  env: {
+    memory,
+    wc_log: (ptr, len) => {
+      const bytes = new Uint8Array(memory.buffer).slice(ptr, ptr + len);
+      const text = new TextDecoder().decode(bytes);
+      console.log(`[cart:t${tid}]`, text);
+    },
+    wc_asset_size: assetSize,
+    wc_load_asset: loadAsset,
+    emscripten_notify_memory_growth: () => {},
+    emscripten_asm_const_int: () => 0,
+    emscripten_asm_const_double: () => 0.0,
+    emscripten_get_element_css_size: () => 0,
+    __syscall_getcwd: () => -1,
+    __syscall_getdents64: () => -1,
+  },
+  wasi_snapshot_preview1: {
+    fd_close: () => 0,
+    fd_write: (fd, iovs, iovs_len, nwritten_ptr) => {
+      try {
+        const view = new DataView(memory.buffer);
+        const u8 = new Uint8Array(memory.buffer);
+        let totalWritten = 0;
+        let text = '';
+        for (let i = 0; i < iovs_len; i++) {
+          const ptr = view.getUint32(iovs + i * 8, true);
+          const len = view.getUint32(iovs + i * 8 + 4, true);
+          if (len > 0) text += new TextDecoder().decode(u8.slice(ptr, ptr + len));
+          totalWritten += len;
+        }
+        if (text && (fd === 1 || fd === 2)) {
+          for (const line of text.split('\n')) {
+            if (line.length > 0) process.stderr.write(`[cart:t${tid}] ${line}\n`);
+          }
+        }
+        if (nwritten_ptr) view.setUint32(nwritten_ptr, totalWritten, true);
+      } catch {}
+      return 0;
+    },
+    fd_seek: () => 0,
+    fd_read: () => 0,
+    environ_get: () => 0,
+    environ_sizes_get: () => 0,
+    proc_exit: () => {},
+    clock_time_get: (id, precision, resultPtr) => {
+      try {
+        const ns = BigInt(Math.round(performance.now() * 1e6));
+        new DataView(memory.buffer).setBigUint64(resultPtr, ns, true);
+      } catch {}
+      return 0;
+    },
+    sched_yield: () => 0,
+  },
+  wasi: {
+    'thread-spawn': (arg) => {
+      // Nested thread spawning: request main thread to do it
+      // For now, use synchronous message exchange
+      // TODO: use Atomics.wait/notify for true sync if needed
+      parentPort.postMessage({ type: 'spawn', startArg: arg });
+      // Return -1 for now (nested spawn needs async handling)
+      // Full implementation would use Atomics.wait on a shared buffer
+      return -1;
+    },
+  },
+};
+
+// Provide GL stubs if the module imports GL functions (they must not be called from workers)
+const moduleImports = WebAssembly.Module.imports(wasmModule);
+for (const imp of moduleImports) {
+  if (imp.kind !== 'function') continue;
+  // GL functions in 'gl' module
+  if (imp.module === 'gl') {
+    if (!imports.gl) imports.gl = {};
+    imports.gl[imp.name] = () => {
+      throw new Error(`GL call ${imp.name}() not allowed from worker thread ${tid}`);
+    };
+  }
+  // GL functions in 'env' module (gl4es pattern)
+  if (imp.module === 'env' && (imp.name.startsWith('gl') || imp.name.startsWith('emscripten_gl'))) {
+    if (!(imp.name in imports.env)) {
+      imports.env[imp.name] = () => {
+        throw new Error(`GL call ${imp.name}() not allowed from worker thread ${tid}`);
+      };
+    }
+  }
+  // Other unknown env functions - provide no-op stubs to avoid instantiation failure
+  if (imp.module === 'env' && !(imp.name in imports.env)) {
+    imports.env[imp.name] = () => 0;
+  }
+  // Unknown wasi_snapshot_preview1 functions - no-op stubs
+  if (imp.module === 'wasi_snapshot_preview1' && !(imp.name in imports.wasi_snapshot_preview1)) {
+    imports.wasi_snapshot_preview1[imp.name] = () => 0;
+  }
+}
+
+// --- Instantiate and run ---
+
+async function run() {
+  const instance = await WebAssembly.instantiate(wasmModule, imports);
+
+  // Call the thread entry point
+  instance.exports.wasi_thread_start(tid, startArg);
+
+  // Thread function returned - clean up and notify main thread
+  if (assetFd !== null) {
+    try { closeSync(assetFd); } catch {}
+  }
+  parentPort.postMessage({ type: 'exit', tid });
+}
+
+run().catch(err => {
+  console.error(`[thread ${tid}] fatal:`, err.message);
+  if (assetFd !== null) {
+    try { closeSync(assetFd); } catch {}
+  }
+  parentPort.postMessage({ type: 'exit', tid, error: err.message });
+});

package/src/cartWorkerWeb.js

@@ -0,0 +1,170 @@
+/**
+ * cartWorkerWeb.js - WASI threads worker for browser
+ *
+ * Receives a compiled WebAssembly.Module and shared WebAssembly.Memory
+ * via postMessage, instantiates the module, and calls
+ * wasi_thread_start(tid, start_arg).
+ */
+
+let inflateSync = null;
+
+let memory;
+let tid;
+let assetBuf = null;
+let assetIndex = null;
+
+function readZipEntryFromBuffer(buf, entry) {
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+  const nameLen = view.getUint16(entry.localHeaderOffset + 26, true);
+  const extraLen = view.getUint16(entry.localHeaderOffset + 28, true);
+  const dataOffset = entry.localHeaderOffset + 30 + nameLen + extraLen;
+
+  const compressedData = buf.subarray(dataOffset, dataOffset + entry.compressedSize);
+
+  if (entry.compressionMethod === 0) return compressedData;
+  if (entry.compressionMethod === 8) {
+    if (!inflateSync) throw new Error('fflate not loaded - cannot decompress asset');
+    return inflateSync(compressedData);
+  }
+  return null;
+}
+
+function assetSize(pathPtr, pathLen) {
+  if (!assetIndex) return -1;
+  const path = new TextDecoder().decode(new Uint8Array(memory.buffer, pathPtr, pathLen));
+  const entry = assetIndex.get(path);
+  return entry ? entry.uncompressedSize : -1;
+}
+
+function loadAsset(pathPtr, pathLen, destPtr, maxSize) {
+  if (!assetIndex) return -1;
+  const path = new TextDecoder().decode(new Uint8Array(memory.buffer, pathPtr, pathLen));
+  const entry = assetIndex.get(path);
+  if (!entry) return -1;
+  if (entry.uncompressedSize > maxSize) return -1;
+
+  let data;
+  if (assetBuf) {
+    data = readZipEntryFromBuffer(assetBuf, entry);
+  } else {
+    return -1;
+  }
+  if (!data) return -1;
+
+  const dest = new Uint8Array(memory.buffer, destPtr, data.length);
+  dest.set(data.subarray ? data.subarray(0, data.length) : new Uint8Array(data, 0, data.length));
+  return data.length;
+}
+
+self.onmessage = async function(e) {
+  const { module: wasmModule, memory: sharedMemory, tid: threadId, startArg, assetConfig } = e.data;
+  memory = sharedMemory;
+  tid = threadId;
+
+  // Set up asset access
+  if (assetConfig && assetConfig.type === 'buffer' && assetConfig.buffer) {
+    assetBuf = new Uint8Array(assetConfig.buffer);
+    assetIndex = new Map(assetConfig.index);
+    // Load fflate dynamically for asset decompression
+    try {
+      const fflate = await import('fflate');
+      inflateSync = fflate.inflateSync;
+    } catch (e) {
+      console.warn(`[thread] fflate not available - compressed assets will fail`);
+    }
+  }
+
+  const imports = {
+    env: {
+      memory,
+      wc_log: (ptr, len) => {
+        const bytes = new Uint8Array(memory.buffer).slice(ptr, ptr + len);
+        const text = new TextDecoder().decode(bytes);
+        console.warn(`[cart:t${tid}]`, text);
+      },
+      wc_asset_size: assetSize,
+      wc_load_asset: loadAsset,
+      emscripten_notify_memory_growth: () => {},
+      emscripten_asm_const_int: () => 0,
+      emscripten_asm_const_double: () => 0.0,
+      emscripten_get_element_css_size: () => 0,
+      __syscall_getcwd: () => -1,
+      __syscall_getdents64: () => -1,
+    },
+    wasi_snapshot_preview1: {
+      fd_close: () => 0,
+      fd_write: (fd, iovs, iovs_len, nwritten_ptr) => {
+        try {
+          const view = new DataView(memory.buffer);
+          const u8 = new Uint8Array(memory.buffer);
+          let totalWritten = 0;
+          let text = '';
+          for (let i = 0; i < iovs_len; i++) {
+            const ptr = view.getUint32(iovs + i * 8, true);
+            const len = view.getUint32(iovs + i * 8 + 4, true);
+            if (len > 0) text += new TextDecoder().decode(u8.slice(ptr, ptr + len));
+            totalWritten += len;
+          }
+          if (text && (fd === 1 || fd === 2)) {
+            console.warn(`[cart:t${tid}]`, text);
+          }
+          if (nwritten_ptr) view.setUint32(nwritten_ptr, totalWritten, true);
+        } catch {}
+        return 0;
+      },
+      fd_seek: () => 0,
+      fd_read: () => 0,
+      environ_get: () => 0,
+      environ_sizes_get: () => 0,
+      proc_exit: () => {},
+      clock_time_get: (id, precision, resultPtr) => {
+        try {
+          const ns = BigInt(Math.round(performance.now() * 1e6));
+          new DataView(memory.buffer).setBigUint64(resultPtr, ns, true);
+        } catch {}
+        return 0;
+      },
+      sched_yield: () => 0,
+    },
+    wasi: {
+      'thread-spawn': (arg) => {
+        self.postMessage({ type: 'spawn', startArg: arg });
+        return -1;
+      },
+    },
+  };
+
+  // Stub GL and unknown imports
+  const moduleImports = WebAssembly.Module.imports(wasmModule);
+  for (const imp of moduleImports) {
+    if (imp.kind !== 'function') continue;
+    if (imp.module === 'gl') {
+      if (!imports.gl) imports.gl = {};
+      imports.gl[imp.name] = () => {
+        throw new Error(`GL call ${imp.name}() not allowed from worker thread ${tid}`);
+      };
+    }
+    if (imp.module === 'env' && (imp.name.startsWith('gl') || imp.name.startsWith('emscripten_gl'))) {
+      if (!(imp.name in imports.env)) {
+        imports.env[imp.name] = () => {
+          throw new Error(`GL call ${imp.name}() not allowed from worker thread ${tid}`);
+        };
+      }
+    }
+    if (imp.module === 'env' && !(imp.name in imports.env)) {
+      imports.env[imp.name] = () => 0;
+    }
+    if (imp.module === 'wasi_snapshot_preview1' && !(imp.name in imports.wasi_snapshot_preview1)) {
+      imports.wasi_snapshot_preview1[imp.name] = () => 0;
+    }
+  }
+
+  try {
+    const instance = await WebAssembly.instantiate(wasmModule, imports);
+    instance.exports.wasi_thread_start(tid, startArg);
+    self.postMessage({ type: 'exit', tid });
+  } catch (err) {
+    console.error(`[thread ${tid}] fatal:`, err.message);
+    self.postMessage({ type: 'exit', tid, error: err.message });
+  }
+};