listepo · listepo · Aug 6, 2026 · Aug 6, 2026 · Aug 6, 2026 · Aug 6, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -9,6 +9,7 @@ on:
 permissions:
   actions: read
   contents: read
+  pull-requests: write
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -110,6 +111,23 @@ jobs:
           rustup component add llvm-tools-preview
           pnpm exec nx run-many -t coverage
 
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: |
+            packages/ns-wasm-core/test-output/vitest/coverage/lcov.info
+            packages/ns-wasm3/test-output/vitest/coverage/lcov.info
+            packages/ns-wamr/test-output/vitest/coverage/lcov.info
+            packages/ns-wasm-kit-runtime/test-output/vitest/coverage/lcov.info
+            packages/ns-wasm-chicory/test-output/vitest/coverage/lcov.info
+            packages/ns-wasm-edge/test-output/vitest/coverage/lcov.info
+            packages/ns-endive/test-output/vitest/coverage/lcov.info
+            packages/ns-wry/test-output/vitest/coverage/lcov.info
+            packages/vitest-ns/test-output/vitest/coverage/lcov.info
+            packages/vitest-ns-ui/test-output/vitest/coverage/lcov.info
+            packages/ns-wasm-fixture/target/coverage/lcov.info
+
       # Rust is pre-installed on GitHub's ubuntu-latest runner. When debugging
       # locally with `act` the slim image may not have it — install on the fly
       # so the same workflow is self-contained.
@@ -172,21 +190,21 @@ jobs:
           changed="$(git diff --name-only "$base...HEAD")" || run_all
 
           echo "$changed"
-          if grep -qE '^(packages/ns-wasm3/|\.github/workflows/ci\.yml$)' <<<"$changed"; then
+          if grep -qE '^(packages/ns-wasm3/|packages/ns-wasm-core/|\.github/workflows/ci\.yml$)' <<<"$changed"; then
             echo "wasm3=true" >> "$GITHUB_OUTPUT"
           else
             echo "wasm3=false" >> "$GITHUB_OUTPUT"
           fi
 
-          if grep -qE '^(packages/ns-wamr/|\.github/workflows/ci\.yml$)' <<<"$changed"; then
+          if grep -qE '^(packages/ns-wamr/|packages/ns-wasm-core/|\.github/workflows/ci\.yml$)' <<<"$changed"; then
             echo "wamr=true" >> "$GITHUB_OUTPUT"
           else
             echo "wamr=false" >> "$GITHUB_OUTPUT"
           fi
 
           # The app's suite runs the plugin end to end, so a plugin or fixture
           # change is as relevant to it as a change to the app itself.
-          if grep -qE '^(apps/ns-wasm-test/|packages/ns-wasm3/|packages/ns-wamr/|packages/ns-wasm-fixture/|\.github/workflows/ci\.yml$)' <<<"$changed"; then
+          if grep -qE '^(apps/ns-wasm-test/|packages/ns-wasm3/|packages/ns-wamr/|packages/ns-wasm-kit-runtime/|packages/ns-endive/|packages/ns-wasm-chicory/|packages/ns-wasm-edge/|packages/ns-wasm-core/|packages/ns-wasm-fixture/|\.github/workflows/ci\.yml$)' <<<"$changed"; then
             echo "app=true" >> "$GITHUB_OUTPUT"
           else
             echo "app=false" >> "$GITHUB_OUTPUT"
@@ -459,7 +477,7 @@ jobs:
       # The app snapshots local file: dependencies when pnpm installs them, so
       # every package whose entry point lives in dist/ must be built first.
       - name: Build the app's local packages
-        run: pnpm exec nx run-many -t build -p ns-wasm3 ns-wamr vitest-ns vitest-ns-ui
+        run: pnpm exec nx run-many -t build -p ns-wasm-core ns-wasm3 ns-wamr ns-wasm-kit-runtime ns-endive ns-wasm-chicory ns-wasm-edge vitest-ns vitest-ns-ui
 
       - name: Install the test app's dependencies
         working-directory: apps/ns-wasm-test
@@ -497,7 +515,7 @@ jobs:
       # Keep this before the app install: pnpm snapshots local file: packages,
       # including their generated dist/ entry points, into app node_modules.
       - name: Build the app's local packages
-        run: pnpm exec nx run-many -t build -p ns-wasm3 ns-wamr vitest-ns vitest-ns-ui
+        run: pnpm exec nx run-many -t build -p ns-wasm-core ns-wasm3 ns-wamr ns-wasm-kit-runtime ns-endive ns-wasm-chicory ns-wasm-edge vitest-ns vitest-ns-ui
 
       - name: Install the test app's dependencies
         working-directory: apps/ns-wasm-test

diff --git a/.mise.toml b/.mise.toml
@@ -5,25 +5,13 @@
 node = "24.18.1"
 java = "temurin-21.0.2"
 "npm:pnpm" = "11.20.0"
+buck2 = "latest"
 
 [settings]
-# Use Temurin as the default Java distribution
-java.default_distribution = "temurin"
 
 # ── Notes ───────────────────────────────────────────────────────────────────
 # - Swift 6.3+ and Xcode 16+ are managed by macOS / Xcode.app, not mise.
 # - Kotlin 2.4.x and Android NDK 29 are pulled by the Gradle project.
 # - Gradle 9.6.1 is managed by the committed wrapper (gradlew), not mise.
 # - pnpm is managed by mise via the npm backend (see [tools] above).
 #   The version matches "packageManager" in root package.json.
-#
-# Buck2 is NOT available via cargo (the crates.io "buck2" crate v0.1.1 is a
-# placeholder). Install it once with the prebuilt binary (~107 MB, no toolchain
-# needed):
-#
-#   curl -fsSL https://github.com/facebook/buck2/releases/latest/download/buck2-aarch64-apple-darwin.zst | zstd -d | sudo tee /usr/local/bin/buck2 > /dev/null && sudo chmod +x /usr/local/bin/buck2
-#
-# Or use the community asdf plugin (mise-compatible, downloads prebuilt):
-#   mise plugin install buck2 https://github.com/izaakschroeder/asdf-buck2
-#   buck2 = "latest"   # then uncomment the line below
-# buck2 = "latest"
diff --git a/.oxfmtrc.json b/.oxfmtrc.json
@@ -0,0 +1,12 @@
+{
+  "ignorePatterns": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/.buck-out/**",
+    "**/target/**",
+    "**/.build/**",
+    "**/platforms/**",
+    "**/src/vendors/**",
+    "**/test-output/**"
+  ]
+}
diff --git a/.oxlintrc.json b/.oxlintrc.json
@@ -0,0 +1,31 @@
+{
+  "$schema": "https://raw.githubusercontent.com/oxc-project/oxc/main/crates/oxc_linter/src/schema.json",
+  "plugins": ["typescript", "import", "unicorn"],
+  "rules": {
+    "no-unused-vars": "error",
+    "no-console": "warn",
+    "typescript/no-non-null-assertion": "warn",
+    "import/no-default-export": "off"
+  },
+  "env": {
+    "node": true,
+    "es2022": true
+  },
+  "globals": {
+    "globalThis": "readonly",
+    "NSData": "readonly",
+    "NSMutableArray": "readonly"
+  },
+  "settings": {},
+  "ignorePatterns": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/.buck-out/**",
+    "**/target/**",
+    "**/.build/**",
+    "**/platforms/**",
+    "**/src/vendors/**",
+    "**/test-output/**",
+    "**/*.d.ts"
+  ]
+}
diff --git a/AGENTS.md b/AGENTS.md
@@ -37,13 +37,23 @@
 
 ## NativeScript plugins in this repo
 
-Three sibling plugins live under `packages/`, all sharing the same
-architecture: Rust cargo workspace, UniFFI (uniffi-rs) Kotlin/Swift bindings,
-and a TypeScript adapter. The two WASM plugins are mirror images of each
-other (same class shapes, same wire protocol, same error mapping). Everything
-the plugins share is documented in [Shared plugin architecture](#shared-plugin-architecture)
-below; each package's AGENTS.md holds only engine-specific detail.
-
+Several sibling plugins live under `packages/`, all sharing the same
+TypeScript API (wire protocol, error mapping, and `WasmRuntime` / `WasmModule` /
+`WasmFunction` class shapes). The Rust cargo workspace and UniFFI (uniffi-rs)
+Kotlin/Swift bindings — together with the mirror-image native architecture
+described in [Shared plugin architecture](#shared-plugin-architecture) — apply
+to **ns-wasm3 and ns-wamr**. The newer runtimes (`ns-wasm-kit-runtime`, the
+Swift-native WasmKit interpreter; `ns-endive`, the Java-native Endive
+interpreter) share the same TypeScript adapter pattern, wire protocol, and
+`@cross-code/ns-wasm-core` foundation, but have their own per-engine native
+layers. Only engine-specific detail lives in each package's AGENTS.md.
+
+- **`ns-wasm-core`** (`@cross-code/ns-wasm-core`) — shared foundation package
+  providing the wire protocol (`parseSignature`, `toWire`, `fromWire`,
+  `WasmError`), the native adapter interfaces (`NativeRuntimeAdapter`,
+  `NativeModuleAdapter`, `NativeFunctionAdapter`), and the generic
+  `WasmRuntime`/`WasmModule`/`WasmFunction` base classes that every WASM
+  runtime plugin extends.
 - **`ns-wasm3`** (`@cross-code/ns-wasm3`) — mature plugin binding
   the wasm3 interpreter (Swift Package on iOS, Kotlin + Rust JNI (cargo-ndk) on Android).
   See `packages/ns-wasm3/AGENTS.md`.
@@ -53,6 +63,11 @@ below; each package's AGENTS.md holds only engine-specific detail.
   builds enable only the interpreter (see [Key differences](#key-differences-wasm3-vs-wamr)).
   WAMR-2.3.0 sources are vendored at `packages/ns-wamr/src/vendors/wamr/`.
   See `packages/ns-wamr/AGENTS.md`.
+- **`ns-wasm-kit-runtime`** (`@cross-code/ns-wasm-kit-runtime`) — plugin wrapping
+  the [WasmKit](https://github.com/swiftwasm/WasmKit) Swift interpreter.
+  iOS-only at this time (WasmKit is Swift-native and served through SwiftPM);
+  Android throws a clear unsupported error. Follows the same TypeScript
+  adapter pattern as the other two plugins.
 - **`ns-wry`** (`@cross-code/ns-wry`) — general-purpose NativeScript plugin
   scaffold built on Rust + UniFFI (uniffi-rs) with cargo-ndk Android pipeline.
   See `packages/ns-wry/AGENTS.md` for the bare-metal architecture; extend the
@@ -80,7 +95,7 @@ until sources are present.
 
 ## Shared plugin architecture
 
-Both plugins follow the same architecture: a platform-agnostic wire protocol
+The WASM runtime plugins follow the same architecture: a platform-agnostic wire protocol
 (`src/lib/wire.ts`), per-platform TypeScript adapter files, Swift `@objc`
 classes on iOS, Kotlin + Rust JNI on Android, and Nx targets declared via
 `package.json`. Substitute `<Engine>` = `Wasm3`-family
@@ -129,6 +144,28 @@ Swapping those groups is a common mistake — verify the regex carefully. The
 native layers convert this notation to the engine's own format internally
 (WAMR's native format is `"(params)returns"`).
 
+### TypeScript typing guidelines for native adapters
+
+The workspace uses `noImplicitAny: true` and `strict: true`. Follow these
+conventions when writing TypeScript adapter code that bridges to native layers:
+
+- **Use `unknown` over `any`** for opaque bridge values (error refs, callback
+  handles, runtime proxy objects). Cast to a concrete interface only at the
+  call site.
+- **Define proxy interfaces** in `src/lib/native-proxy.d.ts` for each native
+  class shape (e.g. `NativeChicoryRuntimeProxy`, `IosWasmEdgeFunctionProxy`).
+  The interfaces model the actual bridge methods; the native layer creates
+  the objects, TypeScript only calls them.
+- **Error ref tuples**: iOS error out-params use `[unknown]` tuple typing
+  so they can be spread into method signatures. The `withErrorRef` helper
+  returns the error ref as `[unknown] | null`.
+- **globalThis shape**: Define a `NativeScriptOrg` interface in
+  `native-proxy.d.ts` for `globalThis.org.nativescript.*` access. Cast
+  `globalThis as unknown as NativeScriptOrg` — never `as any`.
+- **Callback narrowing**: When passing a `WireHostCallback` to a native
+  constructor that expects `(args: unknown[]) => unknown[]`, cast explicitly:
+  `cb as (args: unknown[]) => unknown[]`.
+
 ### Missing imports surface at `findFunction`
 
 Both engines compile functions lazily. A missing imported function is
@@ -542,8 +579,10 @@ wasm-pack-generated `.d.ts`. See `packages/ns-wasm-fixture/README.md`.
 
 | Path                                    | Contents                                                                |
 | --------------------------------------- | ----------------------------------------------------------------------- |
+| `packages/ns-wasm-core/AGENTS.md`       | (none — shared foundation; see Shared plugin architecture above)        |
 | `packages/ns-wasm3/AGENTS.md` | wasm3-specific: stack ABI, globals, fixtures, build/test                |
 | `packages/ns-wamr/AGENTS.md`  | WAMR-specific: two-phase load, exec env, WASI, tiers, trampolines, shim |
+| `packages/ns-wasm-kit-runtime/AGENTS.md` | WasmKit-specific: iOS-only Swift interpreter, Android unsupported stub |
 | `packages/ns-wry/AGENTS.md`            | wry scaffold: Rust + UniFFI architecture, platform stubs, extension guide  |
 | `apps/ns-wasm-test/AGENTS.md` | test app: layout, design decisions, running the suites, adding specs       |
 | `apps/ns-wry-app`                      | test app: WebView demo, build-plugin-and-run workflow                       |

diff --git a/README.md b/README.md
@@ -1,22 +1,29 @@
 # cross-code
 
 An Nx monorepo for running WebAssembly on [NativeScript](https://nativescript.org) —
-three sibling plugins built on Rust + UniFFI:
+three WASM runtime plugins built on a shared TypeScript foundation (wire protocol,
+adapter interfaces, base Runtime/Module/Function classes):
 
 - [`wasm3`](https://github.com/wasm3/wasm3) — lightweight interpreter (v0.5.2)
 - [WAMR](https://github.com/bytecodealliance/wasm-micro-runtime) — WebAssembly
   Micro Runtime (2.3.0): interpreter, Fast JIT, LLVM JIT, AOT, WASI
-- [`ns-wry`](packages/ns-wry) — Rust + [UniFFI](https://github.com/mozilla/uniffi-rs)
-  (uniffi-rs) auto-generated Kotlin/Swift bindings, cargo-ndk Android pipeline
+- [WasmKit](https://github.com/swiftwasm/WasmKit) — Swift-based WebAssembly
+  runtime with WASI support, iOS-native through SwiftPM
+
+Also in the monorepo: [`ns-wry`](packages/ns-wry) — a general-purpose NativeScript
+plugin scaffold built on Rust + [UniFFI](https://github.com/mozilla/uniffi-rs)
+(uniffi-rs) auto-generated Kotlin/Swift bindings and cargo-ndk Android pipeline.
 
 > **Project status: Active development.** APIs and project layout may change without notice; expect breaking changes between releases.
 
 ## Packages
 
 | Package                                                                       | Description                                                                                                                             |
 | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| [`@cross-code/ns-wasm-core`](packages/ns-wasm-core)       | Shared foundation — wire protocol, `WasmError`, adapter interfaces, base `WasmRuntime`/`WasmModule`/`WasmFunction` classes              |
 | [`@cross-code/ns-wasm3`](packages/ns-wasm3)               | NativeScript plugin — Swift Package on iOS, Kotlin + Rust JNI (cargo-ndk) on Android (wasm3 interpreter)                                |
 | [`@cross-code/ns-wamr`](packages/ns-wamr)                 | NativeScript plugin — Swift Package on iOS, Kotlin + Rust JNI (cargo-ndk) on Android (WAMR: interpreter, Fast JIT, LLVM JIT, AOT, WASI) |
+| [`@cross-code/ns-wasm-kit-runtime`](packages/ns-wasm-kit-runtime) | NativeScript plugin — Swift Package on iOS (WasmKit interpreter); Android throws a clear unsupported error                      |
 | [`@cross-code/ns-wasm-fixture`](packages/ns-wasm-fixture) | Rust/wasm-pack test fixtures (committed `.wasm` binaries)                                                                               |
 | [`@cross-code/vitest-ns`](packages/vitest-ns)             | Vitest custom pool and NativeScript Worker runtime for on-device unit tests                                                             |
 | [`@cross-code/vitest-ns-ui`](packages/vitest-ns-ui)       | Optional NativeScript Core results page for device-side Vitest progress                                                                 |
@@ -25,7 +32,10 @@ three sibling plugins built on Rust + UniFFI:
 | [`ns-wasm-test`](apps/ns-wasm-test)                       | NativeScript test app — runs the plugins on a simulator/emulator from a demo page and through Vitest + `vitest-ns`            |
 | [`ns-wry-app`](apps/ns-wry-app)                                               | NativeScript test app for @cross-code/ns-wry — WebView demo with google.com on iOS/Android                                              |
 
-Both plugins expose the same TypeScript API — see [WASM.md](WASM.md).
+The WASM runtime plugins expose the same TypeScript API — see [WASM.md](WASM.md). All runtime
+plugins (wasm3, WAMR, WasmKit) share the same foundation (`@cross-code/ns-wasm-core`)
+which provides the wire protocol, error classes, adapter interfaces and generic
+`WasmRuntime`/`WasmModule`/`WasmFunction` classes.
 Each package README covers its own layout, development workflow and troubleshooting
 (see [Per-package documentation](#per-package-documentation)).
 
@@ -141,24 +151,54 @@ curl -fsSL https://github.com/facebook/buck2/releases/latest/download/buck2-aarc
 
 or `mise plugin install buck2 https://github.com/izaakschroeder/asdf-buck2`.
 
-## WebAssembly plugins (wasm3 & WAMR)
+## WebAssembly plugins (wasm3, WAMR & WasmKit)
 
-Usage and API documentation for the two WebAssembly plugins — install,
+Usage and API documentation for the WebAssembly plugins — install,
 quick start, calling exports, linear memory, globals, host imports, value
 marshalling, error messages, the complete API reference, and shared
 troubleshooting — lives in **[WASM.md](WASM.md)**.
 
-Both plugins expose the same TypeScript API; only the class names differ
+All three plugins expose the same TypeScript API; only the class names differ
 (`Wasm3Runtime` / `Wasm3Module` / `Wasm3Function` vs
-`WamrRuntime` / `WamrModule` / `WamrFunction`).
+`WamrRuntime` / `WamrModule` / `WamrFunction` vs
+`WasmKitRuntime` / `WasmKitModule` / `WasmKitFunction`).
+WasmKit is iOS-only (Swift-based runtime); Android throws a clear "not supported" error.
+
+## Linting
+
+### Kotlin (Android wrappers)
+
+```bash
+# Detekt (static analysis) + Ktlint (formatting) — hand-written sources only
+pnpm exec nx run ns-wasm3:lint.android
+pnpm exec nx run ns-wasm3:lint.android --configuration=format  # auto-fix
+
+# Config: detekt.yml + .editorconfig at the repo root (shared by both engines)
+```
+
+### Swift (iOS wrappers)
+
+```bash
+# SwiftLint — hand-written sources only
+pnpm exec nx run ns-wasm3:lint.ios
+pnpm exec nx run ns-wamr:lint.ios
+
+# Periphery — unused-code detection (builds the SwiftPM package)
+pnpm exec nx run ns-wasm3:periphery.ios
+pnpm exec nx run ns-wamr:periphery.ios
+
+# Config: .swiftlint.yml + .periphery.yml at the repo root (shared by all engines)
+```
 
 ## Per-package documentation
 
 | Package                                 | Docs                                                                                                                     |
 | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| WebAssembly plugins (wasm3 & WAMR)      | [WASM.md](WASM.md) — shared usage, API reference, marshalling, errors, troubleshooting                                    |
+| WebAssembly plugins (wasm3, WAMR & WasmKit) | [WASM.md](WASM.md) — shared usage, API reference, marshalling, errors, troubleshooting                                    |
+| `@cross-code/ns-wasm-core`      | [AGENTS.md](AGENTS.md#shared-plugin-architecture) — wire protocol, WasmError, adapter interfaces, base classes |
 | `@cross-code/ns-wasm3`        | [README](packages/ns-wasm3/README.md) — platform details, package layout, developing, troubleshooting, license |
 | `@cross-code/ns-wamr`         | [README](packages/ns-wamr/README.md) — execution tiers, package layout, developing, troubleshooting, license   |
+| `@cross-code/ns-wasm-kit-runtime` | [README](packages/ns-wasm-kit-runtime/README.md) — WasmKit Swift interpreter, iOS-only adapter, developing, troubleshooting |
 | `@cross-code/ns-wasm-fixture` | [README](packages/ns-wasm-fixture/README.md) — exported subpaths, rebuilding the `.wasm` fixtures              |
 | `@cross-code/vitest-ns`       | [README](packages/vitest-ns/README.md) — custom pool, Worker registry, concurrency, and transport              |
 | `@cross-code/vitest-ns-ui`    | [README](packages/vitest-ns-ui/README.md) — optional NativeScript results UI                                   |