docs: update README & AGENTS for ns-wasm-core and ns-wasm-kit-runtime

.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.
@@ -124,6 +142,15 @@ jobs:
       - name: Rust unit tests
         run: pnpm exec nx run ns-wasm-fixture:test.wasm
 
+      # Clippy + rustfmt over the hand-written Rust in all four Rust projects
+      # (ns-wasm3, ns-wamr, ns-wry, ns-wasm-fixture). Generated bindings
+      # (bindgen output, UniFFI scaffolding) are excluded: bindgen output is
+      # `#![rustfmt::skip]` and `clippy::all` is allowed around the includes.
+      - name: Rust lint (Clippy) + format check
+        run: |
+          rustup component add clippy rustfmt
+          pnpm exec nx run-many -t lint.rust fmt.rust -p ns-wasm3 ns-wamr ns-wry ns-wasm-fixture
+
       # globals.wasm is committed but generated, and the generator is
       # deterministic — so a stale copy is a hard error rather than a surprise
       # on someone's device. (test_types_bg.wasm needs wasm-pack to rebuild and
@@ -172,21 +199,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 +486,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 +524,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

.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"

.oxfmtrc.json

@@ -0,0 +1,12 @@
+{
+  "ignorePatterns": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/.buck-out/**",
+    "**/target/**",
+    "**/.build/**",
+    "**/platforms/**",
+    "**/src/vendors/**",
+    "**/test-output/**"
+  ]
+}

.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"
+  ]
+}

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
@@ -496,6 +533,39 @@ casts are the assertions). Periphery found and removed real dead code in
 keep `lint.ios` and `periphery.ios` green; CI runs both in the `wasm3-ios`
 and `wamr-ios` jobs.
 
+### Rust linting (Clippy + Rustfmt)
+
+Each Rust workspace — `ns-wasm3` (`src/vendors/wasm3-rust`), `ns-wamr`
+(`src/vendors/wamr-rust`), `ns-wry` (`src/vendors/wry-rust`), and the fixture
+crate `ns-wasm-fixture` (`src/test-types`) — is linted with **Clippy** and
+checked with **Rustfmt**. Generated code never reaches the tools: bindgen
+output is written to `OUT_DIR` and `#![allow(clippy::all)]` covers the
+`include!`s, the one committed reference copy
+(`wamr-sys/src/bindings.rs`) is `#![rustfmt::skip]`, and UniFFI scaffolding
+(`include_scaffolding!` / `setup_scaffolding!`) expands in `OUT_DIR`. The JNI
+crates (`wasm3-jni`, `wamr-jni`) allow `clippy::not_unsafe_ptr_arg_deref`
+crate-wide — `#[no_mangle] extern "system"` entry points deref raw JVM-owned
+pointer args by design.
+
+The `uniffi-bindgen` scaffolding bins (`*/ffi/src/bin/uniffi-bindgen.rs`) are
+excluded by config, not by editing them: each `[[bin]]` carries `test = false`
+in its crate's `Cargo.toml` so `cargo clippy --lib --tests` never compiles it,
+and the `fmt.rust`/`format.rust` scripts format the `find`-listed `.rs` files
+minus any named `uniffi-bindgen.rs` (rustfmt's `ignore` config is nightly-only,
+so the file filter lives in the script).
+
+```bash
+pnpm exec nx run <pkg>:lint.rust    # cargo clippy --all-features --lib --tests -- -D warnings
+pnpm exec nx run <pkg>:fmt.rust     # find + rustfmt --check --edition 2021 (excludes uniffi-bindgen.rs)
+pnpm exec nx run <pkg>:format.rust  # find + rustfmt --edition 2021 (auto-fix)
+pnpm exec nx run-many -t lint.rust fmt.rust -p ns-wasm3 ns-wamr ns-wry ns-wasm-fixture
+```
+
+CI runs the `run-many` form in the `unit-tests` job (Rust is preinstalled on
+the GitHub runner). Requires the `clippy` and `rustfmt` rustup components
+(`rustup component add clippy rustfmt`). The `fmt.rust`/`format.rust` scripts
+honour `#![rustfmt::skip]` on generated files — don't reformat them by hand.
+
 Code coverage, per project and per language:
 
 - **TypeScript** — every package's vitest config has a `coverage` block
@@ -542,8 +612,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                       |