Merge pull request #505 from gridaco/canary

Grida Canvas - emscripten node target (render without browser)

Author: softmarshmallow

crates/grida-canvas-wasm/.cargo/config.toml

@@ -1,7 +1,7 @@
 [profile.release]
-opt-level = 3           # optimize for size ("z" has runtime performance impact, keep this 3)
-lto = true              # use link time optimization
-codegen-units = 1       # allow cross-crate inlining & dedup
+opt-level = 3 # optimize for size ("z" has runtime performance impact, keep this 3)
+lto = true # use link time optimization
+codegen-units = 1 # allow cross-crate inlining & dedup
 # NOTE:
 # Newer Rust stable toolchains ship `wasm32-unknown-emscripten` std/core built
 # with `panic=unwind`. If we force `panic=abort` here, rustc fails with:
@@ -10,7 +10,7 @@ codegen-units = 1       # allow cross-crate inlining & dedup
 # with nightly `-Z build-std` (core + panic_abort) for wasm32-unknown-emscripten.
 # `panic=unwind` increases the wasm size by 0.5mb compared to `panic=abort`
 panic = "unwind"
-strip = "symbols"       # strip symbols from final artifact
+strip = "symbols" # strip symbols from final artifact
 debug = false
 
 
@@ -34,31 +34,34 @@ linker = "emcc"
 
 # Linker arguments passed to Emscripten
 rustflags = [
-    # Allow undefined symbols (useful for dynamic linking and Skia integration)
-    "-C", "link-arg=-sERROR_ON_UNDEFINED_SYMBOLS=0",
-    
-    # Currently only targeting web (fs=false)
-    # Target web environment (browser) instead of Node.js
-    # We will be removing this once we figure out to make SSR/CSR not fail.
-    "-C", "link-arg=-sENVIRONMENT=web",
-    
-    # Enable WebGL2 support for hardware-accelerated graphics
-    "-C", "link-arg=-sMAX_WEBGL_VERSION=2",
-    "-C", "link-arg=-sUSE_WEBGL2=1",
-    
-    # Allow dynamic memory growth (important for large graphics operations)
-    "-C", "link-arg=-sALLOW_MEMORY_GROWTH=1",
-    "-C", "link-arg=-sINITIAL_MEMORY=256MB",
-    
-    # Create modular output (factory function instead of global Module)
-    "-C", "link-arg=-sMODULARIZE=1",
-    
-    # Set the export function name for the modular output
-    "-C", "link-arg=-sEXPORT_NAME=createGridaCanvas",
-    
-    # Export specific runtime methods for JavaScript access
-    # GL: WebGL context access
-    # UTF8 functions: String conversion utilities
-    # HEAP functions: Direct memory access for performance-critical operations
-    "-C", "link-arg=-sEXPORTED_RUNTIME_METHODS=['GL','lengthBytesUTF8','stringToUTF8','UTF8ToString','HEAP32','HEAPU8','HEAPU16','HEAPU32','HEAPF32']"
+  # Allow undefined symbols (useful for dynamic linking and Skia integration)
+  "-C",
+  "link-arg=-sERROR_ON_UNDEFINED_SYMBOLS=0",
+  # Currently only targeting web (fs=false)
+  # Target both web (browser) and Node.js.
+  # NOTE: this affects the generated Emscripten JS glue (loader/runtime selection).
+  "-C",
+  "link-arg=-sENVIRONMENT=web,node",
+  # Enable WebGL2 support for hardware-accelerated graphics
+  "-C",
+  "link-arg=-sMAX_WEBGL_VERSION=2",
+  "-C",
+  "link-arg=-sUSE_WEBGL2=1",
+  # Allow dynamic memory growth (important for large graphics operations)
+  "-C",
+  "link-arg=-sALLOW_MEMORY_GROWTH=1",
+  "-C",
+  "link-arg=-sINITIAL_MEMORY=256MB",
+  # Create modular output (factory function instead of global Module)
+  "-C",
+  "link-arg=-sMODULARIZE=1",
+  # Set the export function name for the modular output
+  "-C",
+  "link-arg=-sEXPORT_NAME=createGridaCanvas",
+  # Export specific runtime methods for JavaScript access
+  # GL: WebGL context access
+  # UTF8 functions: String conversion utilities
+  # HEAP functions: Direct memory access for performance-critical operations
+  "-C",
+  "link-arg=-sEXPORTED_RUNTIME_METHODS=['GL','lengthBytesUTF8','stringToUTF8','UTF8ToString','HEAP32','HEAPU8','HEAPU16','HEAPU32','HEAPF32']",
 ]

crates/grida-canvas-wasm/AGENTS.md

@@ -10,6 +10,31 @@ as new apis are introduced via `main.rs`, we also need to update the `grida-canv
 
 Note: the artifacts are git included for faster CI builds.
 
+## Bundler compatibility (Next.js Turbopack + dual-env Emscripten glue)
+
+When building the WASM glue with `-sENVIRONMENT=web,node`, Emscripten emits a Node-only branch that uses Node built-ins (`fs`, `path`, sometimes `crypto`). Some bundlers (notably **Next.js Turbopack**) will still try to resolve those built-ins when the module is imported from a Client Component and fail with **"Can't resolve 'fs'"**.
+
+We keep a **single package** that works in both browser and Node by combining three measures:
+
+- **Patch Emscripten glue to use `node:*` built-ins**
+  - Script: `scripts/prebuild-patch-emscripten-js-glue.cjs`
+  - Patched file: `lib/bin/grida-canvas-wasm.js`
+  - Rewrites `require("fs")` → `require("node:fs")`, `require("path")` → `require("node:path")`, `require("crypto")` → `require("node:crypto")`
+  - Reference issue: `https://github.com/emscripten-core/emscripten/issues/26134`
+
+- **Do NOT bundle the Emscripten glue into `dist/index.*`**
+  - `lib/index.ts` imports `./grida-canvas-wasm` (a thin wrapper)
+  - Wrapper: `lib/grida-canvas-wasm.ts` imports `./bin/grida-canvas-wasm`
+  - `tsup.config.ts` sets `external: ["./grida-canvas-wasm"]` and copies `lib/bin/*` via `publicDir`
+  - Result: `dist/index.js` only imports `./grida-canvas-wasm`, and the actual glue stays as `dist/grida-canvas-wasm.js` (copied), so Turbopack never sees Node built-ins inside the bundled entry.
+
+- **Run the glue patch before bundling**
+  - `package.json` uses `prebuild` to patch `lib/bin/grida-canvas-wasm.js` before `tsup` runs.
+
+⚠️ Notes:
+- Simply setting `tsup.external` to `["node:fs", "node:path", ...]` is **not sufficient** here; bundling the glue can still produce `require("fs")` in `dist/index.js`, which breaks Turbopack.
+- If you change `lib/index.ts` to import `./bin/grida-canvas-wasm` directly (no wrapper + external), re-verify `pnpm --filter editor build` with Turbopack.
+
 ## Build System
 
 This project uses a unified `justfile` build system for all WASM build configurations.

crates/grida-canvas-wasm/README.md

@@ -8,6 +8,8 @@ WASM bindings for Grida Canvas.
 pnpm install @grida/canvas-wasm
 ```
 
+### Browser (WebGL)
+
 ```ts
 import init from "@grida/canvas-wasm";
 
@@ -26,6 +28,29 @@ const scene = factory.createWebGLCanvasSurface(canvas);
 scene.loadDummyScene();
 ```
 
+### Node (raster export)
+
+```ts
+import { createCanvas } from "@grida/canvas-wasm";
+import { readFileSync, writeFileSync } from "node:fs";
+
+const canvas = await createCanvas({
+  backend: "raster",
+  width: 256,
+  height: 256,
+});
+
+const doc = readFileSync("example/rectangle.grida1", "utf8");
+canvas.loadScene(doc);
+
+const { data } = canvas.exportNodeAs("rectangle", {
+  format: "PNG",
+  constraints: { type: "none", value: 1 },
+});
+
+writeFileSync("out.png", Buffer.from(data));
+```
+
 ## Serving locally for development
 
 For local development, this package has `serve` ready.

crates/grida-canvas-wasm/example/gradient.grida1

@@ -0,0 +1,68 @@
+{
+  "version": "0.90.0-beta+20260108",
+  "document": {
+    "nodes": {
+      "gradient-rect": {
+        "id": "gradient-rect",
+        "name": "gradient-rect",
+        "locked": false,
+        "active": true,
+        "layout_positioning": "absolute",
+        "layout_inset_top": 24,
+        "layout_inset_left": 24,
+        "opacity": 1,
+        "z_index": 0,
+        "rotation": 0,
+        "layout_target_width": 208,
+        "layout_target_height": 208,
+        "type": "rectangle",
+        "corner_radius": 32,
+        "effects": [],
+        "stroke_width": 0,
+        "stroke_cap": "butt",
+        "fill_paints": [
+          {
+            "type": "linear_gradient",
+            "active": true,
+            "stops": [
+              {
+                "offset": 0,
+                "color": { "r": 0.94, "g": 0.33, "b": 0.31, "a": 1 }
+              },
+              {
+                "offset": 1,
+                "color": { "r": 0.25, "g": 0.48, "b": 0.96, "a": 1 }
+              }
+            ]
+          }
+        ]
+      },
+      "main": {
+        "type": "scene",
+        "id": "main",
+        "name": "main",
+        "active": true,
+        "locked": false,
+        "constraints": {
+          "children": "multiple"
+        },
+        "guides": [],
+        "edges": [],
+        "background_color": {
+          "r": 0.96,
+          "g": 0.96,
+          "b": 0.96,
+          "a": 1
+        }
+      }
+    },
+    "links": {
+      "main": ["gradient-rect"]
+    },
+    "scenes_ref": ["main"],
+    "bitmaps": {},
+    "images": {},
+    "properties": {}
+  }
+}
+

crates/grida-canvas-wasm/justfile

@@ -71,7 +71,7 @@ info:
     @echo "Configuration:"
     @echo "  - Linker arguments configured in .cargo/config.toml"
     @echo "  - ERROR_ON_UNDEFINED_SYMBOLS=0 (allow undefined symbols)"
-    @echo "  - ENVIRONMENT=web (web environment)"
+    @echo "  - ENVIRONMENT=web,node (web + node environments)"
     @echo "  - MAX_WEBGL_VERSION=2 (WebGL2 support)"
     @echo "  - ALLOW_MEMORY_GROWTH=1 (dynamic memory growth)"
     @echo "  - MODULARIZE=1 (modular output)"

crates/grida-canvas-wasm/lib/__test__/.gitignore

@@ -0,0 +1 @@
+out