wasmcart 0.2.0

package/bin/wasmcart-pack.js

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+
+/**
+ * wasmcart-pack - Package a .wasm cart + assets into a .wasc archive
+ *
+ * Usage:
+ *   wasmcart-pack --wasm build/cart.wasm --assets assets/ --output game.wasc
+ *   wasmcart-pack --wasm build/cart.wasm --output game.wasc  (no assets)
+ *   wasmcart-pack --wasm build/cart.wasm --assets assets/ --name "My Game" --version "1.0.0" --output game.wasc
+ */
+
+import { createWriteStream, readFileSync, statSync, readdirSync } from 'fs';
+import { resolve, relative, join, basename, extname } from 'path';
+import { ZipFile } from 'yazl';
+
+// Parse arguments
+const args = process.argv.slice(2);
+let wasmPath = null;
+let assetsDir = null;
+let outputPath = null;
+let gameName = null;
+let gameVersion = '1.0.0';
+let players = null;
+let netWebsocket = null;  // array of domain strings
+let netDataChannel = false;
+let usePointer = false;
+let useKeyboard = false;
+
+for (let i = 0; i < args.length; i++) {
+  switch (args[i]) {
+    case '--wasm':
+      wasmPath = resolve(args[++i]);
+      break;
+    case '--assets':
+      assetsDir = resolve(args[++i]);
+      break;
+    case '--output':
+    case '-o':
+      outputPath = resolve(args[++i]);
+      break;
+    case '--name':
+      gameName = args[++i];
+      break;
+    case '--version':
+      gameVersion = args[++i];
+      break;
+    case '--players':
+      players = parseInt(args[++i], 10);
+      break;
+    case '--ws':
+    case '--websocket':
+      if (!netWebsocket) netWebsocket = [];
+      netWebsocket.push(args[++i]);
+      break;
+    case '--data-channel':
+      netDataChannel = true;
+      break;
+    case '--pointer':
+      usePointer = true;
+      break;
+    case '--keyboard':
+      useKeyboard = true;
+      break;
+    case '--help':
+    case '-h':
+      printUsage();
+      process.exit(0);
+      break;
+    default:
+      if (!args[i].startsWith('-')) {
+        // Positional: treat as wasm path if not set, else output
+        if (!wasmPath) wasmPath = resolve(args[i]);
+        else if (!outputPath) outputPath = resolve(args[i]);
+      }
+      break;
+  }
+}
+
+if (!wasmPath) {
+  console.error('Error: --wasm <path> is required');
+  printUsage();
+  process.exit(1);
+}
+
+if (!outputPath) {
+  // Default: same name as wasm but with .wasc extension
+  outputPath = resolve(basename(wasmPath, extname(wasmPath)) + '.wasc');
+}
+
+if (!gameName) {
+  gameName = basename(wasmPath, extname(wasmPath));
+}
+
+// Validate wasm file exists
+try {
+  statSync(wasmPath);
+} catch {
+  console.error(`Error: WASM file not found: ${wasmPath}`);
+  process.exit(1);
+}
+
+// Validate new fields
+if (players !== null) {
+  if (!Number.isInteger(players) || players < 1 || players > 4) {
+    console.error('Error: --players must be an integer between 1 and 4');
+    process.exit(1);
+  }
+}
+
+if (netWebsocket) {
+  for (const domain of netWebsocket) {
+    if (!domain || domain.includes('/') || domain.includes(':') || domain.startsWith('.')) {
+      console.error(`Error: invalid WebSocket domain: "${domain}" (must be a bare domain name)`);
+      process.exit(1);
+    }
+  }
+}
+
+// Build manifest
+const manifest = {
+  name: gameName,
+  version: gameVersion,
+  abi: 3,
+  entry: 'cart.wasm',
+};
+
+if (players !== null && players > 1) {
+  manifest.players = players;
+}
+
+if (usePointer) {
+  manifest.pointer = true;
+}
+
+if (useKeyboard) {
+  manifest.keyboard = true;
+}
+
+if (netWebsocket || netDataChannel) {
+  manifest.net = {};
+  if (netWebsocket) manifest.net.websocket = netWebsocket;
+  if (netDataChannel) manifest.net['data-channel'] = true;
+}
+
+if (assetsDir) {
+  manifest.assets = 'assets/';
+}
+
+// Collect asset files
+function walkDir(dir, base) {
+  const files = [];
+  const entries = readdirSync(dir);
+
+  for (const entry of entries) {
+    if (entry.startsWith('.')) continue;
+    const fullPath = join(dir, entry);
+    const relPath = join(base, entry);
+
+    try {
+      const s = statSync(fullPath);
+      if (s.isDirectory()) {
+        files.push(...walkDir(fullPath, relPath));
+      } else if (s.isFile()) {
+        files.push({ fullPath, relPath: relPath.replace(/\\/g, '/') });
+      }
+    } catch {
+      // Skip inaccessible files
+    }
+  }
+
+  return files;
+}
+
+// Create ZIP
+const zipfile = new ZipFile();
+
+// Add manifest.json
+const manifestJson = JSON.stringify(manifest, null, 2);
+zipfile.addBuffer(Buffer.from(manifestJson), 'manifest.json');
+
+// Add cart.wasm (store without compression - wasm is already compact)
+zipfile.addFile(wasmPath, 'cart.wasm', { compress: false });
+
+// Add asset files
+let assetCount = 0;
+let assetBytes = 0;
+
+if (assetsDir) {
+  try {
+    statSync(assetsDir);
+  } catch {
+    console.error(`Error: Assets directory not found: ${assetsDir}`);
+    process.exit(1);
+  }
+
+  const assetFiles = walkDir(assetsDir, '');
+  for (const { fullPath, relPath } of assetFiles) {
+    const zipPath = 'assets/' + relPath;
+    zipfile.addFile(fullPath, zipPath);
+    const s = statSync(fullPath);
+    assetCount++;
+    assetBytes += s.size;
+  }
+}
+
+// Write output
+const outputStream = createWriteStream(outputPath);
+zipfile.outputStream.pipe(outputStream);
+
+outputStream.on('close', () => {
+  const outSize = statSync(outputPath).size;
+  const wasmSize = statSync(wasmPath).size;
+
+  console.log(`Created: ${outputPath}`);
+  console.log(`  WASM:   ${formatSize(wasmSize)}`);
+  if (assetCount > 0) {
+    console.log(`  Assets: ${assetCount} files, ${formatSize(assetBytes)} (uncompressed)`);
+  }
+  console.log(`  Total:  ${formatSize(outSize)}`);
+});
+
+zipfile.end();
+
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+}
+
+function printUsage() {
+  console.log(`wasmcart-pack - Package a .wasm cart + assets into a .wasc archive`);
+  console.log(``);
+  console.log(`Usage: wasmcart-pack --wasm <cart.wasm> [--assets <dir>] --output <game.wasc>`);
+  console.log(``);
+  console.log(`Options:`);
+  console.log(`  --wasm <path>      Path to the compiled cart.wasm file (required)`);
+  console.log(`  --assets <dir>     Directory of assets to include`);
+  console.log(`  --output, -o       Output .wasc file path (default: <name>.wasc)`);
+  console.log(`  --name <name>      Game name for manifest (default: wasm filename)`);
+  console.log(`  --version <ver>    Game version for manifest (default: 1.0.0)`);
+  console.log(`  --players <n>      Number of local players (1-4, default: 1)`);
+  console.log(`  --ws <domain>      Allow WebSocket to domain (repeatable)`);
+  console.log(`  --data-channel     Enable data channel (peer-to-peer)`);
+  console.log(`  --pointer          Enable pointer input (mouse/touch)`);
+  console.log(`  --keyboard         Enable raw keyboard input`);
+  console.log(`  -h, --help         Show this help`);
+  console.log(``);
+  console.log(`The .wasc file is a ZIP archive containing:`);
+  console.log(`  manifest.json    Metadata (name, version, ABI, entry point)`);
+  console.log(`  cart.wasm        The compiled cart (code only)`);
+  console.log(`  assets/          Game assets (textures, levels, audio, etc.)`);
+  console.log(``);
+  console.log(`Examples:`);
+  console.log(`  wasmcart-pack --wasm build/cart.wasm --assets assets/ -o game.wasc`);
+  console.log(`  wasmcart-pack --wasm hello.wasm -o hello.wasc`);
+}

package/docs/bind_framebuffer.md

@@ -0,0 +1,275 @@
+# glBindFramebuffer(target, 0) - Host FBO Redirect
+
+## The Rule
+
+When a cart calls `glBindFramebuffer(GL_FRAMEBUFFER, 0)`, the host MUST redirect this to its display FBO. The cart uses FBO 0 to mean "the screen." The host decides what "the screen" actually is.
+
+## Why This Matters
+
+Carts that use Skia Ganesh GL (wasmcart-jsgame's Canvas 2D) render to an offscreen FBO, then blit to FBO 0:
+
+```
+Game draws → Ganesh offscreen FBO (e.g. FBO 2)
+                    ↓
+         glBlitFramebuffer(FBO 2 → FBO 0)
+                    ↓
+         Host reads display FBO → screen
+```
+
+If the host doesn't intercept `glBindFramebuffer(target, 0)`, the blit goes to the real default framebuffer (FBO 0), which may not be what the host reads.
+
+## How Each Host Handles It
+
+### Browser (CartHostWeb) - Works
+
+WebGL2's `gl.bindFramebuffer(target, null)` binds the canvas backbuffer. The cart calls `glBindFramebuffer(target, 0)`, the host maps ID 0 → `null`, which IS the canvas. The browser composites the canvas to the page. No redirect needed.
+
+### Node.js (retroemu cli.js) - Works
+
+The Node host creates an offscreen FBO (`glFBO`) with a color texture + depth/stencil renderbuffer. It intercepts `glBindFramebuffer`:
+
+```javascript
+gl.glBindFramebuffer = (target, fb) => {
+    const actual = fb === 0 ? glFBO : fb;
+    _origBindFB.call(gl, target, actual);
+};
+```
+
+When the cart binds FBO 0, the host redirects to `glFBO`. After `wc_render()`, the host blits from `glFBO` to the window surface via `glBlitFramebuffer`, then calls `swapBuffers`.
+
+### wasmcart-native (standalone) - Works (redirect FBO)
+
+The native host creates a redirect FBO via `wc_gl_setup_redirect()`. `gl_imports.cpp` intercepts `glBindFramebuffer(target, 0)` → redirect FBO. After `wc_render()`, `wc_gl_blit_to_screen()` blits redirect FBO → real FBO 0 (EGL window surface) with letterboxing, then calls `eglSwapBuffers`.
+
+### RetroArch (libretro) - WORKS (redirect FBO)
+
+RetroArch uses `hw_render` which gives the core a specific FBO via `get_current_framebuffer()`. The wasmcart libretro core uses the shared `gl_imports.cpp` FBO redirect (same code as wasmcart-native via git submodule). When the cart binds FBO 0, the redirect intercepts it to our capture FBO. After `wc_render()`, `libretro.c` blits from the capture FBO → RetroArch's hw_render FBO.
+
+**NOTE (2026-03-31): The FBO redirect works correctly. Verified by readPixels:**
+
+```
+Ganesh FBO center pixel:  R=252 G=216 B=168 A=255  ← game content in Ganesh's offscreen FBO
+Blit TARGET center pixel: R=252 G=216 B=168 A=255  ← same content in redirect FBO after blit
+```
+
+The cart's blit delivers full game content to FBO 0 (redirect). The content is verified
+present in the redirect FBO. But RetroArch displays only the background.
+
+This means the issue is in the HOST's final blit from redirect FBO → RetroArch's
+hw_render FBO (or RetroArch's compositing of the hw_render FBO to screen).
+
+**Debugging done on cart side:**
+- Shaders: `#version 300 es` accepted by Mesa Core 3.3 (GL_ARB_ES3_compatibility) - no patching needed
+- Shader compile: all pass
+- Program link: all pass
+- GL errors: none
+- Ganesh FBO readPixels: full game content present
+- Redirect FBO readPixels AFTER blit: full game content present
+- `glBlitFramebuffer` from Ganesh FBO → FBO 0: works (content verified in target)
+
+**What to check on host side (wasmcart-native gl_imports.cpp / libretro.c):**
+1. Does `wc_gl_blit_to_screen()` correctly blit redirect FBO → hw_render FBO?
+2. Is the blit Y-flipped? The redirect FBO content is kTopLeft (Y=0 at top, Skia convention).
+   The hw_render FBO might expect kBottomLeft (Y=0 at bottom, GL convention). If so, the
+   blit needs to flip Y: `glBlitFramebuffer(0, H, W, 0, 0, 0, W, H, ...)`.
+3. Is the blit happening AFTER wc_render returns? The redirect FBO is populated during
+   wc_render. If the host blits before wc_render completes, it reads stale content.
+4. Does RetroArch's hw_render FBO have the correct format (RGBA8, same as redirect)?
+5. Is the redirect FBO being cleared BEFORE the blit reads from it? Check for glClear
+   calls between wc_render return and the redirect→hw_render blit.
+
+**UPDATE 2 (2026-03-31): CONFIRMED HOST-SIDE ISSUE**
+
+Tested with BOTH GPU (Ganesh) AND CPU (Skia raster + GL blit) rendering.
+Both produce correct game content in the redirect FBO. Host-side logging confirms:
+
+```
+Canvas 2D: CPU (Skia raster + GL blit)           ← CPU fallback, no Ganesh
+[pre-blit] rfbo=2 ra_fbo=1 blit=1920x1080
+  center=(252,216,168,255)                        ← game tile color, correct
+  quarter=(252,216,168,255)                       ← also correct
+```
+
+The redirect FBO (rfbo=2) has full game content. RetroArch's FBO (ra_fbo=1) is the
+blit target. The host's blit from rfbo→ra_fbo is not producing visible output.
+
+This is NOT a cart-side issue. NOT a Ganesh issue. NOT a shader issue. The cart
+delivers correct pixels to FBO 0 (redirect) via both GPU and CPU paths. The host's
+final blit from redirect FBO → RetroArch's hw_render FBO is broken.
+
+**UPDATE 3 (2026-03-31): GL CALL TRACES PROVE HOST ISSUE**
+
+Captured full GL call traces on Node (working) and RetroArch (failing). The call
+sequences are FUNCTIONALLY IDENTICAL:
+
+```
+Node frame 5:                           RetroArch frame 5:
+glBindFramebuffer(0x8d40, 1)            glBindFramebuffer(0x8d40, 3)
+glViewport(0, 0, 800, 600)             glViewport(0, 0, 1920, 1080)
+glClearColor(0.99, 0.85, 0.66, 1.0)    glClearColor(0.99, 0.85, 0.66, 1.0)
+glClear(0x4000)                         glClear(0x4000)
+glUseProgram(1)                         glUseProgram(28)
+glDrawArrays(0x5, 0, 4)                glDrawArrays(0x5, 0, 4)
+glUseProgram(6)       ← textured       glUseProgram(43)      ← textured
+glActiveTexture(0x84c0)                 glActiveTexture(0x84c0)
+glBindTexture(0xde1, 13)                glBindTexture(0xde1, 192)
+glDrawArrays(0x5, 0, 4)                glDrawArrays(0x5, 0, 4)
+... identical pattern continues ...     ... identical pattern continues ...
+```
+
+Same GL calls, same order, same patterns. Only resource IDs differ (expected).
+The cart is doing everything correctly. The HOST's gl_imports.cpp virtual ID
+mapping must be breaking texture or FBO mapping on the RetroArch path.
+
+**UPDATE 4: FULL GL CALL TRACE COMPARISON (2026-03-31)**
+
+Captured 694 GL calls (Node, working) vs 762 calls (RetroArch, failing).
+The call sequences are FUNCTIONALLY IDENTICAL:
+- Same FBO binds (Node: FBO 1, RetroArch: FBO 3)
+- Same texture uploads (glTexSubImage2D with real data)
+- Same program binds (textured program + solid program)
+- Same draw calls (glDrawArrays with same vertex counts/offsets)
+- Same sampler binds (glBindSampler unit 0)
+- Same blend/stencil/scissor state
+- Same clear color (0.99, 0.85, 0.66 = game background)
+
+BUT: RetroArch Ganesh FBO reads as ALL background color at frame 7.
+The 67 textured glDrawArrays calls produce ZERO visible fragments.
+
+**This is proven to be a HOST issue, not a cart issue.** The cart sends
+identical GL commands. The host's gl_imports.cpp must be:
+1. Mapping texture virtual IDs to wrong real GL textures, OR
+2. Mapping FBO virtual ID to wrong real GL FBO, OR
+3. RetroArch is overwriting our GL objects between frames
+
+The other agent needs to add real GL-level inspection (apitrace/renderdoc)
+to see what ACTUAL GL calls reach the driver after the host's ID translation.
+
+**UPDATE 5 (2026-03-31): GANESH WORKS ON RETROARCH!**
+
+The other agent's gl_imports.cpp fix resolved the Ganesh rendering issue.
+Adventure-ai renders fully with GPU-accelerated Canvas 2D on RetroArch.
+
+**BUT: Three.js (direct WebGL, no Ganesh) is now broken on RetroArch.**
+
+The gl_imports.cpp change that fixed Ganesh broke the direct WebGL path.
+The fix MUST work for ALL carts - the host cannot know whether a cart uses
+Ganesh or direct WebGL. The host is a transparent GL passthrough.
+
+**The fix must be unconditionally correct.** Whatever GL behavior was changed
+to fix Ganesh must ALSO be correct for direct WebGL carts. If the change
+altered how a specific GL function works (e.g., internal format translation,
+FBO binding, texture storage), find the version that works for BOTH:
+
+1. Identify exactly which gl_imports.cpp function was changed
+2. Test that function's behavior against both adventure-ai (Ganesh) AND
+   threejs (direct WebGL) AND Godot (direct GL)
+3. The correct behavior is whatever real GLES 3.0 / GL 3.3 does - the host
+   should be a transparent passthrough, not cart-specific
+
+If the fix involved working around a Ganesh quirk by changing GL behavior,
+that's wrong. The host should pass GL calls through unchanged. The cart
+is responsible for generating correct GL calls - and we proved the cart's
+GL calls are identical between working (Node) and failing (RetroArch) hosts.
+
+**Most likely cause:** Y-flip mismatch. The cart's blit to redirect flips Y (Skia
+top-down → GL bottom-up). If the host's blit from redirect→hw_render ALSO flips Y,
+the image is double-flipped. The host should do a 1:1 copy (no flip) since the cart
+already handled the flip. OR: check glBlitFramebuffer src/dst coords in libretro.c.
+
+## The FBO ID Collision Problem
+
+On RetroArch, the hw_render FBO might have the same GL ID as Ganesh's offscreen FBO. This happens because:
+
+1. RetroArch binds its hw_render FBO (e.g. FBO 2) before calling `retro_run()`
+2. During `wc_render()`, Ganesh creates its offscreen render target via `SkSurfaces::RenderTarget`
+3. The wasmcart host's `glGenFramebuffers` goes through the host's GL import table
+4. If the host uses virtual ID mapping (like webgl_imports.js), Ganesh might get a virtual ID that collides with the host's FBO virtual ID
+5. If the host passes through raw GL IDs, Ganesh gets a NEW real FBO (e.g. FBO 3) - no collision
+
+On RetroArch, the wasmcart libretro core appears to use raw GL IDs (no virtual mapping). Ganesh calls `glGenFramebuffers` and gets a new FBO. But from the cart's perspective (via the host's GL imports), both the host's FBO and Ganesh's FBO report as ID 2. This suggests the host IS using virtual ID mapping, and both got virtual ID 2.
+
+Either way: the cart blits to FBO 0. If the host redirects 0 → its display FBO, it works. If it doesn't redirect, the content goes to the wrong place.
+
+## Fix for RetroArch (wasmcart_libretro.so)
+
+The libretro core needs to intercept `glBindFramebuffer` and redirect FBO 0 to the hw_render FBO:
+
+```c
+// In gl_imports.cpp or wherever GL imports are provided:
+
+static GLuint _hw_render_fbo = 0;
+
+// Called each frame before wc_render():
+void set_hw_render_fbo(GLuint fbo) {
+    _hw_render_fbo = fbo;
+}
+
+// GL import provided to the cart:
+void gl_glBindFramebuffer(GLenum target, GLuint framebuffer) {
+    GLuint actual = (framebuffer == 0 && _hw_render_fbo != 0) ? _hw_render_fbo : framebuffer;
+    glBindFramebuffer(target, actual);
+}
+```
+
+And in `retro_run()`:
+```c
+void retro_run(void) {
+    // Get RetroArch's hw_render FBO for this frame
+    GLuint fbo = hw_render.get_current_framebuffer();
+    set_hw_render_fbo(fbo);
+
+    // Run the cart frame
+    wc_render();
+
+    // RetroArch reads from fbo after we return
+}
+```
+
+This is the same pattern as the Node host's FBO redirect. The cart always blits to FBO 0 meaning "the screen." The host decides where "the screen" is.
+
+## Why This Affects Ganesh Specifically
+
+Other GL carts (Godot, OpenArena) render directly to whatever FBO the host has bound. They don't create their own offscreen FBOs and blit. They call `glClear` + `glDraw*` and the host sees the results in its FBO.
+
+Ganesh is different because it creates its OWN offscreen FBO (for stencil support needed by Canvas 2D path rendering). It renders there, then needs to copy the result to the display. The copy goes to FBO 0, which must be the display.
+
+## Cart-Side Principle
+
+The cart MUST blit to FBO 0 to mean "the display." The cart MUST NOT try to detect or target a specific host FBO by ID. The host is responsible for making FBO 0 the correct target.
+
+This matches the WebGL2 convention: `gl.bindFramebuffer(target, null)` always means the canvas. And the wasmcart spec: the host is a transparent ES 3.0 surface.
+
+## UPDATE 6 (2026-03-31): Direct FBO redirect REVERTED - depth/stencil required
+
+Setting RetroArch's hw_render FBO as the redirect target directly
+(`wc_gl_set_redirect_fbo`) broke ALL GL carts - not just Ganesh. Three.js
+and OpenArena also stopped rendering.
+
+**Root cause:** RetroArch's hw_render FBO does not have depth+stencil
+attachments. Our `wc_gl_setup_redirect` creates an FBO with:
+- Color texture (RGBA8)
+- Depth24+Stencil8 renderbuffer
+
+Three.js needs depth testing. Ganesh needs stencil for path rendering.
+OpenArena needs both. Without these attachments, 3D rendering fails.
+
+**Current architecture (restored):**
+
+```
+Cart draws → redirect FBO (ours, with depth+stencil)
+                    ↓ wc_gl_blit_to_fbo
+            RetroArch hw_render FBO (color only)
+                    ↓ RetroArch composites
+                  Screen
+```
+
+The intermediate blit is required because RetroArch's FBO lacks depth/stencil.
+
+**Ganesh on RetroArch remains broken** (shows only background). The fix is
+cart-side: Ganesh binds VAO 0 which is undefined on Core 3.3 Profile. The
+cart's `wc_gl_get_proc` must redirect `glBindVertexArray(0)` to a real VAO.
+See `wasmcart-jsgame/ganesh.md` UPDATE 3.
+
+**Working on RetroArch:** Three.js, OpenArena, Snake, Warlords, Roboblast
+**Broken on RetroArch:** Adventure-ai (Ganesh VAO 0 - cart-side fix needed)

package/docs/fetch.md

@@ -0,0 +1,105 @@
+# wc_fetch - Network Fetch ABI
+
+## Motivation
+
+Carts currently load local assets via `wc_load_asset` (synchronous, from .wasc bundle). There is no mechanism for carts to make HTTP requests to external servers. Games need this for:
+
+- Loading level data or assets from a CDN
+- Posting high scores / leaderboards
+- User authentication
+- Dynamic content updates
+- Analytics
+
+The WebSocket ABI (`wc_ws_*`) exists but is wrong for request/response patterns. A proper fetch ABI gives carts standard HTTP semantics.
+
+## Design
+
+### Manifest Allowlist
+
+The .wasc `manifest.json` declares which domains the cart may fetch from:
+
+```json
+{
+  "net": {
+    "websocket": ["wss://game-server.example.com"],
+    "fetch": ["https://api.example.com", "https://cdn.example.com"]
+  }
+}
+```
+
+The host validates every fetch URL against this allowlist before proxying. Domains not in the list get a 403 response. This is the security boundary - carts cannot make arbitrary network requests.
+
+### URL Routing (Host Logic)
+
+The host handles ALL fetch requests - both local and network:
+
+1. **Relative path** (e.g. `sounds/laser.mp3`) → load from .wasc bundle. Same as current `wc_load_asset` but through the fetch ABI.
+2. **Absolute URL on allowlist** (e.g. `https://api.example.com/scores`) → host proxies the request using native fetch (Node.js `fetch`, browser `fetch`).
+3. **Absolute URL NOT on allowlist** → return 403 Forbidden.
+4. **Absolute URL, no `net.fetch` in manifest** → return 403.
+
+The cart never knows or cares whether the response came from the bundle or the network. This is transparent.
+
+### Browser Hosts and CORS
+
+In browser-based wasmcart hosts (e.g. a web page running a .wasc), the host's `fetch` call is subject to standard CORS rules. The API server must return `Access-Control-Allow-Origin` headers. This is the server's responsibility, not the cart's or the host's.
+
+In Node.js hosts, there are no CORS restrictions - the host fetches directly.
+
+### Proposed ABI
+
+Fetch is inherently async. The wasmcart ABI is synchronous (wc_render is called per frame). Two approaches:
+
+#### Option A: Callback-based (like WebSocket)
+
+```c
+// Cart imports (host provides):
+int wc_fetch_start(const char* url, uint32_t url_len,
+                   const char* method, uint32_t method_len,
+                   const char* headers, uint32_t headers_len,
+                   const void* body, uint32_t body_len);
+// Returns request_id, or -1 if URL not allowed.
+
+int wc_fetch_state(int request_id);
+// Returns: 0=pending, 1=complete, 2=error
+
+int wc_fetch_response_status(int request_id);
+// Returns HTTP status code (200, 404, etc.)
+
+int wc_fetch_response_size(int request_id);
+// Returns response body size in bytes, or -1 if not complete.
+
+int wc_fetch_response_read(int request_id, void* buf, uint32_t buf_len);
+// Copies response body into buf. Returns bytes copied.
+
+void wc_fetch_response_free(int request_id);
+// Frees the response. Cart must call this when done.
+
+// Cart exports (host calls when response arrives):
+void wc_fetch_on_complete(int request_id);
+void wc_fetch_on_error(int request_id);
+```
+
+The host calls `wc_fetch_on_complete` during the next `wc_render` frame after the response arrives. The cart then reads the response synchronously.
+
+#### Option B: Polling (simpler)
+
+Same imports as above but without the callback exports. Cart polls `wc_fetch_state` each frame. Simpler but adds one frame of latency.
+
+### Recommendation
+
+Option A (callback-based) matches the WebSocket pattern and is lower latency. The host already calls into the cart during `wc_render` (for WebSocket messages), so the infrastructure exists.
+
+### Impact on wasmcart-jsgame
+
+The jsgame cart currently has its own C-level fetch implementation that calls `wc_load_asset` for relative paths and fails on absolute URLs. With `wc_fetch`:
+
+1. **Remove C-level URL routing** - pass ALL fetch URLs to the host via `wc_fetch_start`
+2. **Host handles routing** - relative paths → .wasc bundle, absolute → network proxy
+3. **Simpler cart code** - no URL parsing, no asset loading logic in the cart
+4. **Games get network access** - `fetch('https://api.example.com/scores')` just works (if manifest allows it)
+5. **Same security model** - host enforces allowlist, cart can't bypass it
+
+### Impact on existing carts
+
+Existing carts that only use `wc_load_asset` continue working. `wc_fetch` is an additional import - carts that don't import it aren't affected. Hosts that don't implement it provide stubs (return -1 from `wc_fetch_start`).