@shd101wyy/yo 0.1.17 → 0.1.19

package/.github/skills/yo-syntax/syntax-cheatsheet.md

@@ -0,0 +1,398 @@
+# Yo Syntax Cheatsheet
+
+These are baseline syntax rules for portable Yo code.
+
+## Mental model
+
+- Everything is an expression.
+- Separators change meaning:
+  - commas build tuples, arrays, or struct literals
+  - semicolons create sequencing or type shapes
+- Prefer explicit syntax over relying on parser guesswork.
+
+## Common declaration forms
+
+```rust
+{ println } :: import "std/fmt";
+
+app_name :: "yo-demo";
+
+main :: (fn() -> unit)({
+  value := i32(1);
+  (message : str) = "hello";
+  println(message);
+});
+
+export main;
+```
+
+- Top-level binding: `name :: expr;`
+- Local binding: `name := expr;`
+- Typed binding: `(name : Type) = expr;`
+- Function definition: `name :: (fn(args...) -> ReturnType)(body);`
+
+## Blocks and expressions
+
+| Goal              | Write                      | Avoid                      |
+| ----------------- | -------------------------- | -------------------------- |
+| Single expression | `cond(...)`                | `{ cond(...) }`            |
+| Begin block       | `{ x := i32(1); x }`       | `{ x := i32(1), x }`       |
+| Struct literal    | `{ name: "yo", ok: true }` | `{ name: "yo"; ok: true }` |
+
+```rust
+result := cond(
+  ready => .Ok(()),
+  true => .Err(`not ready`)
+);
+
+total := {
+  base := i32(40);
+  (base + i32(2))
+};
+```
+
+Remember: `{ expr }` without semicolons is a struct literal, not a block.
+
+## Control flow
+
+```rust
+value := cond(
+  (x < i32(0)) => i32(-1),
+  (x == i32(0)) => i32(0),
+  true => i32(1)
+);
+
+label := match(token,
+  .Identifier(name) => name,
+  .Number(_) => "number",
+  .Eof => "eof"
+);
+
+if(done, println("done"), println("pending"));
+```
+
+- Always write `cond(...)`, never bare `cond ...`
+- Always write `match(...)`, never bare `match ...`
+- `if(a, b)` and `if(a, b, c)` are macro forms over `cond`
+
+## String types
+
+| Syntax             | Type              | Context                          |
+| ------------------ | ----------------- | -------------------------------- |
+| `"hello"`          | `str`             | Runtime contexts (most code)     |
+| `"hello"`          | `comptime_string` | Inside `comptime` functions      |
+| `` `hello ${x}` `` | `String`          | Always (template string)         |
+| `` `hello` ``      | `String`          | Always (template without interp) |
+| `*(u8)("hello")`   | `*(u8)`           | Pointer cast for C interop       |
+
+Key rules:
+
+- In **runtime** code, `"hello"` is `str`. Mixing literals and variables in `cond`/`match` branches is fine.
+- In **comptime** functions (return type `comptime(...)`), `"hello"` is `comptime_string` — it does NOT auto-convert to `str`.
+- For `String` constants, prefer `` `hello` `` over `String.from("hello")`.
+
+## Calls, operators, and whitespace
+
+```rust
+sum := add(i32(1), i32(2));
+flag := ((a > b) && (b > c));
+masked := ((A | B) | C);
+```
+
+- Prefer parenthesized calls: `func(arg1, arg2)`
+- `func (a, b)` is a different parse shape than `func(a, b)`
+- Yo has no operator precedence; fully parenthesize binary expressions
+- Parenthesize unary operands: `!(ready)`, `-(value)`
+
+## Functions and methods
+
+```rust
+double :: (fn(x : i32) -> i32)(
+  (x * i32(2))
+);
+
+Counter :: struct(current : i32);
+
+impl(Counter,
+  next : (fn(self : Self) -> i32)({
+    self.current = (self.current + i32(1));
+    self.current
+  })
+);
+```
+
+- No space between a function type and its body: `(fn(...) -> T)(...)`
+- Use `Self` in method signatures
+- Wrap `fn` types in parentheses when they appear after `:`
+
+### Named arguments and default values
+
+```rust
+create_user :: (fn(
+  name : String,
+  (age : i32) ?= 18
+) -> User)(
+  User(name: name, age: age)
+);
+
+create_user(name: `Alice`);
+create_user(name: `Bob`, age: 30);
+```
+
+- Named arguments must keep the same order as the definition
+- Default values use `?=` and must be compile-time known
+
+### Implicit parameters (`using` / `given`)
+
+```rust
+Raise :: (fn(msg : String) -> i32);
+
+safe_divide :: (fn(x : i32, y : i32, using(raise : Raise)) -> i32)(
+  cond(
+    (y == i32(0)) => raise(`divide by zero`),
+    true => (x / y)
+  )
+);
+
+caller :: (fn() -> i32)({
+  (given(raise) : Raise) = (fn(msg : String) -> i32)({
+    return i32(0);
+  });
+
+  safe_divide(i32(10), i32(0))
+});
+```
+
+- `using(name : Type)` declares an implicit parameter (effect)
+- `given(name) := Type(fields...)` installs a handler in the caller's scope
+- Effects are matched by **type**, not by name
+- The handler is auto-resolved at call sites; pass explicitly with `using(name)`
+
+### Closures and anonymous functions
+
+```rust
+(closure : Impl(Fn(x : i32) -> i32)) = ((x) => (x + i32(1)));
+
+result := closure(i32(5));
+
+transform :: (fn(list : ArrayList(i32), f : Impl(Fn(x : i32) -> i32)) -> unit)({
+  for list.iter(), (ptr) => {
+    ptr.* = f(ptr.*);
+  };
+});
+```
+
+- `(params) => expr` — lambda / closure syntax
+- `Impl(Fn(params) -> ReturnType)` — closure type
+- Value types are captured by copy; object types by reference
+- Each closure has a unique type; you cannot assign different closures to the same variable
+
+## Imports and modules
+
+```rust
+{ Parser } :: import "./parser.yo";
+parser_module :: import "./parser.yo";
+
+open import "std/string";
+{ ArrayList } :: import "std/collections/array_list";
+```
+
+- Use relative imports for nearby `.yo` files
+- Use `open import "std/module"` for standard-library modules you want fully in scope
+- Do not write `import "./file.yo" as name`
+- Do not import `std/prelude`
+
+## Enums and pattern matching
+
+```rust
+Option :: (fn(comptime(T) : Type) -> comptime(Type))(
+  enum(None, Some(value : T))
+);
+
+(value : Option(i32)) = .Some(i32(42));
+
+text := match(value,
+  .Some(inner) => "present",
+  .None => "missing"
+);
+```
+
+- Enum definitions omit the leading `.`
+- Construction and match branches use the leading `.`
+- Nested destructuring is not supported; match one layer at a time
+
+## Generics and compile-time
+
+```rust
+identity :: (fn(forall(T : Type), value : T) -> T)(value);
+
+max :: (fn(comptime(a) : i32, comptime(b) : i32) -> comptime(i32))(
+  cond((a > b) => a, true => b)
+);
+
+show :: (fn(forall(T : Type), value : T, where(T <: ToString)) -> unit)(
+  println(value)
+);
+```
+
+- `forall(T : Type)` introduces a generic type parameter
+- `comptime(x) : T` makes a parameter compile-time only
+- `where(T <: Trait)` constrains a type parameter
+- Functions returning `comptime(...)` are evaluated at compile time
+
+## Exports
+
+```rust
+main :: (fn() -> unit)(());
+export main;
+
+export
+  helper,
+  Config
+;
+```
+
+- `export name;` exports a single binding
+- Block form exports multiple bindings separated by commas
+- Every executable needs `export main;`
+
+## Static and dynamic dispatch types
+
+```rust
+show :: (fn(value : Impl(ToString)) -> unit)(
+  println(value)
+);
+
+(erased : Dyn(ToString)) = dyn(i32(42));
+println(erased);
+```
+
+- `Impl(Trait)` — static dispatch; concrete type chosen at compile time
+- `Dyn(Trait)` — dynamic dispatch via trait object
+- `dyn(expr)` wraps a concrete value into its `Dyn(Trait)` form
+
+## Naming conventions
+
+| Kind                        | Style              | Example            |
+| --------------------------- | ------------------ | ------------------ |
+| File / directory / module   | `snake_case`       | `array_list`       |
+| Function / variable         | `snake_case`       | `safe_divide`      |
+| Trait / type / enum variant | `PascalCase`       | `ToString`, `Some` |
+| Constant                    | `UPPER_SNAKE_CASE` | `MAX_SIZE`         |
+
+Use 2-space indentation.
+
+## Recursion and loops
+
+```rust
+factorial :: (fn(n : i32) -> i32)(
+  cond(
+    (n <= i32(1)) => i32(1),
+    true => (n * recur((n - i32(1))))
+  )
+);
+
+while runtime(true), {
+  work();
+};
+```
+
+- Use `recur(...)` for self-recursion
+- `while true` runs at compile time
+- Use `while runtime(true), { ... }` for open-ended runtime loops
+
+## Return and branch safety
+
+```rust
+// WRONG — return consumes the comma, capturing the next match branch:
+match(opt,
+  .Some(v) => return v,    // parsed as return(v, .None => ...)
+  .None => default_value()
+);
+
+// CORRECT — begin blocks isolate return from the comma:
+match(opt,
+  .Some(v) => {
+    return v;
+  },
+  .None => {
+    return default_value();
+  }
+);
+
+// BEST — expression-bodied function, no return needed:
+get_value :: (fn(opt : Option(i32)) -> i32)(
+  match(opt,
+    .Some(v) => v,
+    .None => i32(0)
+  )
+);
+```
+
+- `return expr1, expr2` parses as a single function call: `return(expr1, expr2)`
+- In `cond` or `match` branches, **always use begin blocks** when you need `return`
+- If the whole function is one expression, prefer expression-bodied style and skip `return` entirely
+- The same trap applies to any function call without parens in match branches
+
+## Iterator and for loop
+
+```rust
+{ ArrayList } :: import "std/collections/array_list";
+
+list := ArrayList(i32).new();
+list.push(i32(10));
+list.push(i32(20));
+
+for list.iter(), (ptr) => {
+  println(ptr.*);
+};
+
+for list.into_iter(), (value) => {
+  println(value);
+};
+```
+
+- `for collection, (variable) => { body }` iterates via the `Iterator` trait
+- `.iter()` borrows the collection and yields pointers
+- `.into_iter()` takes ownership and yields values
+
+## Testing
+
+```rust
+test "Addition works", {
+  assert(((i32(1) + i32(1)) == i32(2)), "1+1 should be 2");
+};
+
+test "Compile-time check", {
+  comptime_assert((2 + 2) == 4);
+  comptime_expect_error({ x :: (1 / 0); });
+};
+
+test "Async test", {
+  io.await(yield());
+};
+```
+
+- `test "description", { body }` defines a test — `io : IO` is automatically available
+- All tests can use `io.async(...)`, `io.await(...)`, etc. without a `using` clause
+- `assert(condition, "message")` — runtime assertion (always include a message)
+- `comptime_assert(condition)` — compile-time assertion
+- `comptime_expect_error(expr)` — verify code produces a compile error
+
+## Advanced features (reference)
+
+These features are powerful but less commonly used. Consult the linked docs for full details.
+
+| Feature                | Syntax hint                                              | Documentation                                                                                                          |
+| ---------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Higher-Kinded Types    | `forall(F : (fn(comptime(T) : Type) -> comptime(Type)))` | [DESIGN.md § HKT](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/DESIGN.md#higher-kinded-types-hkt)           |
+| GADTs                  | `enum(IntVal(i : i32) -> recur(i32))`                    | [GADTS.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/GADTS.md)                                           |
+| Derive traits          | `derive(MyType, Eq, Hash, Clone, Ord, ToString)`         | [DERIVE_TRAITS.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/DERIVE_TRAITS.md)                           |
+| Type reflection        | `Type.get_info(T)` returns `TypeInfo`                    | [TYPE_REFLECTION.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/TYPE_REFLECTION.md)                       |
+| Inline assembly        | `asm("mov {0}, #42", out(reg, i32))`                     | [INLINE_ASSEMBLY.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/INLINE_ASSEMBLY.md)                       |
+| Metaprogramming        | `quote(...)`, `unquote(...)`, `unquote_splicing(...)`    | [DESIGN.md § Meta](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/DESIGN.md#meta-programming)                 |
+| Effect row variables   | `forall(...(E))` with `using(...(E))`                    | [ALGEBRAIC_EFFECTS.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/ALGEBRAIC_EFFECTS.md)                   |
+| Custom derive rules    | `derive_rule(MyTrait, (fn(...) -> unquote(Expr)){...})`  | [DERIVE_TRAITS.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/DERIVE_TRAITS.md#user-defined-derive-rules) |
+| Isolated types         | `Iso(T)` for data-race-free parallelism                  | [ISOLATED.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/ISOLATED.md)                                     |
+| Arc (atomic ref count) | `arc(value)`, `shared.(*)` for cross-thread sharing      | [ARC.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/ARC.md)                                               |
+| Parallelism            | Thread pool, `io.spawn` for parallel work                | [PARALLELISM.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/PARALLELISM.md)                               |

package/.github/skills/yo-wasm-integration/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: yo-wasm-integration
+description: Build Yo libraries for WebAssembly and publish as npm packages. Use this when working with WASM targets, Emscripten, WASI, npm packaging, JavaScript/TypeScript wrappers, or browser/Node.js integration.
+argument-hint: "[WASM task, target, or integration question]"
+---
+
+# Yo WASM Integration
+
+Use this skill for compiling Yo projects to WebAssembly and packaging them for JavaScript/TypeScript consumption via npm.
+
+## When to use this skill
+
+Use this skill when you need to:
+
+- compile a Yo project to WebAssembly (Emscripten or WASI)
+- set up an `npm/` package directory with JavaScript/TypeScript wrappers
+- expose Yo functions to JavaScript via WASM memory and C ABI
+- integrate a Yo WASM module into a Node.js or browser project
+- debug WASM-specific compilation or runtime issues
+- publish a Yo-backed npm package
+
+## Workflow
+
+1. Decide on target: Emscripten (browser + Node.js) or WASI (standalone/server).
+2. Define WASM build steps in `build.yo` using `build.executable` with `target: build.CompilationTarget.Wasm32_Emscripten` and `add_c_flags(...)` for Emscripten settings.
+3. Create a JavaScript wrapper in `npm/` that loads the WASM module and exposes a clean API.
+4. Add TypeScript declarations (`index.d.ts`) for type safety.
+5. Test the WASM module from both Node.js and browser contexts.
+6. Consult the [WASM integration cheatsheet](./wasm-integration-cheatsheet.md) for patterns.
+
+## High-signal rules
+
+- In `build.yo`, use `target: build.CompilationTarget.Wasm32_Emscripten` for Emscripten WASM builds. Use `step.add_c_flags(...)` for Emscripten `-s` options.
+- For single-file compilation, use `yo compile --cc emcc` or `yo compile --target wasm-wasi`.
+- WASM functions communicate through linear memory — pass pointers and lengths, not Yo types.
+- JavaScript wrappers handle the string encoding/decoding boundary (`TextEncoder`/`TextDecoder`).
+- Use bitmask flags (powers of 2) to pass option sets through a single `i32` parameter.
+- Yo's `str` and `String` types are internal — export raw `*(u8)` + `usize` pairs for WASM APIs.
+- Always test with `--sanitize address` on native first, then verify WASM behavior matches.
+- Emscripten exports are controlled by `-sEXPORTED_FUNCTIONS` and `-sEXPORTED_RUNTIME_METHODS`.
+- WASM modules can be loaded in Node.js using `WebAssembly.instantiate` or Emscripten's generated JS glue.
+- Errno values differ on WASM — use constants from `std/libc/errno`, never hardcode numbers.
+
+## Resource
+
+- [WASM integration cheatsheet](./wasm-integration-cheatsheet.md)

package/.github/skills/yo-wasm-integration/wasm-integration-cheatsheet.md

@@ -0,0 +1,250 @@
+# Yo WASM Integration Cheatsheet
+
+Patterns for building Yo libraries as WebAssembly modules and consuming them from JavaScript/TypeScript.
+
+## Compilation targets
+
+| Target               | Command                                            | Output                        |
+| -------------------- | -------------------------------------------------- | ----------------------------- |
+| Emscripten (browser) | `yo compile src/api.yo --cc emcc --release -o api` | `.js` + `.wasm`               |
+| WASI (standalone)    | `yo compile src/api.yo --target wasm-wasi -o api`  | `.wasm` (runs via `wasmtime`) |
+| Native (testing)     | `yo compile src/api.yo --release -o api`           | Native binary                 |
+
+## WASM API design pattern
+
+Export C-compatible functions that operate on linear memory:
+
+```rust
+// src/wasm_api.yo
+open import "std/string";
+
+// Allocate WASM memory for the caller
+wasm_alloc :: (fn(size : usize) -> *(u8))(
+  malloc(size)
+);
+
+// Free WASM memory
+wasm_free :: (fn(ptr : *(u8)) -> unit)(
+  free(ptr)
+);
+
+// Process input and return result pointer + length
+render :: (fn(input_ptr : *(u8), input_len : usize, flags : i32) -> *(u8))({
+  (input : str) = str.from_raw_parts(input_ptr, input_len);
+  // ... process input ...
+  result := do_work(input);
+  // Write length to a known location, return pointer
+  result_ptr
+});
+
+export wasm_alloc;
+export wasm_free;
+export render;
+```
+
+Key rules:
+
+- Export only `fn` functions with primitive or pointer types
+- Use `*(u8)` + `usize` for strings across the boundary
+- Use `i32` bitmask flags for option sets (powers of 2)
+- Always provide `wasm_alloc` / `wasm_free` for the JavaScript side
+
+## Bitmask flags pattern
+
+Pass multiple boolean options as a single `i32` using bit flags:
+
+```rust
+// Each option is a power of 2
+// bit 0 = 1   : feature_a
+// bit 1 = 2   : feature_b
+// bit 2 = 4   : feature_c
+// bit 3 = 8   : feature_d
+
+parse_flags :: (fn(flags : i32) -> Options)({
+  (opts : Options) = Options.default();
+  opts.feature_a = ((flags & i32(1)) != i32(0));
+  opts.feature_b = ((flags & i32(2)) != i32(0));
+  opts.feature_c = ((flags & i32(4)) != i32(0));
+  opts.feature_d = ((flags & i32(8)) != i32(0));
+  opts
+});
+```
+
+JavaScript side:
+
+```javascript
+function buildFlags(options) {
+  let flags = 0;
+  if (options.featureA) flags |= 1;
+  if (options.featureB) flags |= 2;
+  if (options.featureC) flags |= 4;
+  if (options.featureD) flags |= 8;
+  return flags;
+}
+```
+
+## build.yo WASM target
+
+The `Executable` struct accepts: `name`, `root`, `target`, `optimize`, `allocator`, `sanitize`.
+Emscripten-specific flags go in `add_c_flags(...)` after creating the step.
+
+```rust
+build :: import "std/build";
+
+wasm_api :: build.executable({
+  name: "my_lib_wasm_api",
+  root: "./src/wasm_api.yo",
+  target: build.CompilationTarget.Wasm32_Emscripten,
+  optimize: build.Optimize.ReleaseSmall,
+  allocator: build.Allocator.Libc
+});
+wasm_api.add_c_flags("-O3 -flto -mbulk-memory -sALLOW_MEMORY_GROWTH -sENVIRONMENT=web,node -sMODULARIZE=1 -sEXPORT_NAME=createModule -sEXPORTED_FUNCTIONS=_wasm_alloc,_wasm_free,_render -sEXPORTED_RUNTIME_METHODS=HEAPU8");
+
+install :: build.step("install", "Build WASM module");
+install.depend_on(wasm_api);
+```
+
+Available targets: `Wasm32_Emscripten`, `Wasm32_Wasi`, `X86_64_Linux_Gnu`, `Aarch64_Macos`, etc.
+Available optimizations: `Debug`, `ReleaseSafe`, `ReleaseFast`, `ReleaseSmall`.
+Available allocators: `Mimalloc` (default), `Libc`.
+
+## npm package structure
+
+```text
+npm/
+├── package.json          # npm package metadata
+├── index.js              # JavaScript wrapper (loads WASM, exposes clean API)
+├── index.d.ts            # TypeScript declarations
+├── my_lib_wasm_api.js    # Emscripten-generated JS glue (build artifact)
+└── my_lib_wasm_api.wasm  # WASM binary (build artifact)
+```
+
+## JavaScript wrapper pattern
+
+```javascript
+// npm/index.js
+const createModule = require("./my_lib_wasm_api.js");
+
+let moduleInstance = null;
+
+async function initModule() {
+  if (!moduleInstance) {
+    moduleInstance = await createModule();
+  }
+  return moduleInstance;
+}
+
+function createRenderer() {
+  let mod = null;
+
+  return {
+    async render(input, options = {}) {
+      if (!mod) mod = await initModule();
+
+      const flags = buildFlags(options);
+      const encoder = new TextEncoder();
+      const inputBytes = encoder.encode(input);
+      const inputLen = inputBytes.length;
+
+      // Allocate WASM memory and copy input
+      const inputPtr = mod._wasm_alloc(inputLen);
+      mod.HEAPU8.set(inputBytes, inputPtr);
+
+      // Call the WASM function
+      const resultPtr = mod._render(inputPtr, inputLen, flags);
+
+      // Read result (assuming null-terminated or length-prefixed)
+      const result = readString(mod, resultPtr);
+
+      // Free memory
+      mod._wasm_free(inputPtr);
+      mod._wasm_free(resultPtr);
+
+      return result;
+    },
+  };
+}
+
+function buildFlags(options) {
+  let flags = 0;
+  if (options.featureA) flags |= 1;
+  if (options.featureB) flags |= 2;
+  return flags;
+}
+
+module.exports = { createRenderer };
+```
+
+## TypeScript declarations
+
+```typescript
+// npm/index.d.ts
+export interface RenderOptions {
+  /** Enable feature A */
+  featureA?: boolean;
+  /** Enable feature B */
+  featureB?: boolean;
+}
+
+export interface Renderer {
+  render(input: string, options?: RenderOptions): Promise<string>;
+}
+
+export function createRenderer(): Renderer;
+```
+
+## String passing across WASM boundary
+
+JavaScript → WASM:
+
+```javascript
+const encoder = new TextEncoder();
+const bytes = encoder.encode(str);
+const ptr = mod._wasm_alloc(bytes.length);
+mod.HEAPU8.set(bytes, ptr);
+// Pass ptr and bytes.length to WASM function
+```
+
+WASM → JavaScript:
+
+```javascript
+// If result is pointer + length
+function readString(mod, ptr, len) {
+  const bytes = mod.HEAPU8.subarray(ptr, ptr + len);
+  return new TextDecoder().decode(bytes);
+}
+
+// If result stores length at a known offset
+function readStringWithStoredLength(mod, ptr, lenPtr) {
+  const len = mod.HEAPU32[lenPtr >> 2];
+  return readString(mod, ptr, len);
+}
+```
+
+## Testing WASM modules
+
+```bash
+# Test native first (fast iteration, AddressSanitizer)
+yo compile src/wasm_api.yo --release --sanitize address -o test && ./test
+
+# Test Emscripten WASM
+yo compile src/wasm_api.yo --cc emcc --release -o npm/my_lib_wasm_api
+
+# Test WASI
+yo compile src/wasm_api.yo --target wasm-wasi -o test.wasm && wasmtime test.wasm
+
+# Run npm package tests
+cd npm && node -e "const m = require('.'); m.createRenderer().render('hello').then(console.log)"
+```
+
+## Common WASM pitfalls
+
+- **Memory leaks**: Always `_wasm_free` every `_wasm_alloc` on the JavaScript side.
+- **String encoding**: WASM only sees bytes — use `TextEncoder`/`TextDecoder` for UTF-8.
+- **Errno differences**: WASI errno values differ from POSIX. Use `std/libc/errno` constants.
+- **No `main` needed**: Library WASM modules don't need `main` or `export main;` — just export the API functions.
+- **Emscripten environment**: Set `-sENVIRONMENT='web,node'` to support both contexts, or `'node'` for Node.js only.
+- **Module initialization is async**: Emscripten's `createModule()` returns a Promise. Initialize once and reuse.
+- **WASM memory growth**: Always use `-sALLOW_MEMORY_GROWTH=1` for dynamic allocations.
+- **Trailing null bytes**: If your Yo code writes null-terminated strings, the JavaScript reader must know to stop at `\0` or use explicit length.
+- **Native testing first**: Always debug with `--sanitize address` on native before switching to WASM — error messages are much clearer.