feat(wasm): KPM detection binding + browser NFT demo (#161 goal 4)

The wasm NFT scaffolding only did AR2 tracking from a hardcoded pose — there
was no KPM detection binding. Add it so the browser demo runs the real
pure-Rust KPM detection (the simple_nft.rs steps 3a + 4).

- core: add `KpmRefDataSet::load_from_bytes` (refactor `load` to share a
  reader-based parser) so `.fset3` can be loaded from fetched bytes in the
  browser (no filesystem). Native parity test vs `load(path)`.
- wasm: add `WasmKpmHandle` — `new(param, w, h)` builds a `RustFreakMatcher`
  + `KpmHandle`; `load_ref_data(.fset3 bytes)`; `detect(rgba)` runs
  `kpm_matching` and returns `{ pose:[12], page, error }` (or null).
- demo: `www/simple_nft_example.html` now fetches `pinball.fset3`, creates a
  `WasmKpmHandle`, and the "Detect (KPM)" button runs real detection, prints
  the 3x4 pose, and feeds it into AR2 tracking (replacing the hardcoded pose).
- test: headless `wasm-bindgen-test` (run via `wasm-pack test`) covering
  construction + `.fset3` load + pre-load detect guard.

Verified in-browser (manual): KPM detection on pinball-demo.jpg yields
page 0, error 5.0879, and a 3x4 pose matching the native simple_nft
pipeline (~5.09 error) — the pure-Rust KPM->pose pipeline runs end-to-end in
the browser. Also: `cargo build --target wasm32-unknown-unknown -p
webarkitlib-wasm --tests` clean; `cargo clippy --all-targets --all-features
-D warnings` clean; native kpm tests green.

Closes #161.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: kalwalt

crates/core/src/kpm/ref_data_set.rs

@@ -45,7 +45,7 @@
 //! [`merge`](KpmRefDataSet::merge), and
 //! [`change_page_no`](KpmRefDataSet::change_page_no).
 
-use std::io::{Read, Write};
+use std::io::Write;
 use std::path::Path;
 
 use byteorder::{LittleEndian, ReadBytesExt, WriteBytesExt};
@@ -405,8 +405,18 @@ impl KpmRefDataSet {
     /// Load a data set from a binary file written by [`save`](Self::save).
     pub fn load(path: &Path) -> std::io::Result<Self> {
         let file = std::fs::File::open(path)?;
-        let mut r = std::io::BufReader::new(file);
+        Self::load_from_reader(std::io::BufReader::new(file))
+    }
+
+    /// Load a data set from in-memory bytes (e.g. a `.fset3` fetched in the
+    /// browser, where there is no filesystem). Same format as [`load`](Self::load).
+    pub fn load_from_bytes(bytes: &[u8]) -> std::io::Result<Self> {
+        Self::load_from_reader(std::io::Cursor::new(bytes))
+    }
 
+    /// Parse a data set from any reader. Shared by [`load`](Self::load) and
+    /// [`load_from_bytes`](Self::load_from_bytes).
+    fn load_from_reader<R: std::io::Read>(mut r: R) -> std::io::Result<Self> {
         let num = r.read_i32::<LittleEndian>()?;
         if num <= 0 {
             return Err(std::io::Error::new(
@@ -728,4 +738,28 @@ mod tests {
     // The test data lives in crates/kpm/examples/data/ and CARGO_MANIFEST_DIR
     // now points to crates/core/. The test is covered by
     // crates/kpm/tests/regression.rs::test_fset3_load_structure.
+
+    /// `load_from_bytes` (the wasm-friendly loader added for #161) must parse a
+    /// real `.fset3` identically to the path-based `load`.
+    #[cfg(not(target_arch = "wasm32"))]
+    #[cfg_attr(miri, ignore)] // reads + parses a 625 KB .fset3 — too slow under Miri
+    #[test]
+    fn test_load_from_bytes_matches_load() {
+        let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+            .join("examples")
+            .join("Data")
+            .join("pinball.fset3");
+        let from_path = KpmRefDataSet::load(&path).expect("load(path) failed");
+        let bytes = std::fs::read(&path).expect("read failed");
+        let from_bytes = KpmRefDataSet::load_from_bytes(&bytes).expect("load_from_bytes failed");
+
+        assert_eq!(from_path.num, from_bytes.num);
+        assert_eq!(from_path.page_num, from_bytes.page_num);
+        assert_eq!(from_path.ref_point.len(), from_bytes.ref_point.len());
+        // Spot-check the first ref point round-trips identically.
+        assert_eq!(
+            from_path.ref_point[0].feature_vec.v,
+            from_bytes.ref_point[0].feature_vec.v
+        );
+    }
 }

crates/wasm/src/lib.rs

@@ -62,6 +62,12 @@ use webarkitlib_rs::types::{
 };
 use webarkitlib_rs::version;
 
+// KPM detection (the `simple_nft.rs` steps 3a + 4 surface).
+use std::sync::Arc;
+use webarkitlib_rs::kpm::ref_data_set::KPM_CHANGE_PAGE_NO_ALL_PAGES;
+use webarkitlib_rs::kpm::types::KpmRefDataSet;
+use webarkitlib_rs::kpm::{KpmHandle, RustFreakMatcher};
+
 /// Returns the current version string of the library.
 #[wasm_bindgen]
 pub fn get_version() -> String {
@@ -643,3 +649,122 @@ impl Drop for WasmNFTHandle {
         }
     }
 }
+
+/// Result of [`WasmKpmHandle::detect`]: the detected 3×4 pose (row-major, 12
+/// floats), the matched page number, and the matching error.
+#[derive(serde::Serialize)]
+struct KpmDetectResult {
+    pose: [f32; 12],
+    page: i32,
+    error: f32,
+}
+
+/// KPM (Keypoint Matching) detection handle — the WASM equivalent of
+/// `simple_nft.rs` steps 3a + 4. Loads NFT reference data (`.fset3`) and
+/// detects the marker's initial 3×4 pose in a query frame using the pure-Rust
+/// [`RustFreakMatcher`].
+///
+/// Pair with [`WasmNFTHandle`] for AR2 tracking: feed `detect()`'s pose into
+/// [`WasmNFTHandle::set_initial_pose`].
+#[wasm_bindgen]
+pub struct WasmKpmHandle {
+    handle: KpmHandle,
+    width: i32,
+    height: i32,
+    loaded: bool,
+}
+
+#[wasm_bindgen]
+impl WasmKpmHandle {
+    /// Create a KPM detection handle.
+    ///
+    /// * `param_bytes` — `camera_para.dat` contents.
+    /// * `width` / `height` — query-frame size in pixels.
+    #[wasm_bindgen(constructor)]
+    pub fn new(param_bytes: &[u8], width: i32, height: i32) -> Result<WasmKpmHandle, JsValue> {
+        let cursor = Cursor::new(param_bytes);
+        let mut param = ARParam::load(cursor)
+            .map_err(|e| JsValue::from_str(&format!("Failed to load camera param: {}", e)))?;
+
+        // Scale camera params to the frame size (arParamChangeSize equivalent).
+        let sx = width as f64 / param.xsize as f64;
+        let sy = height as f64 / param.ysize as f64;
+        for col in 0..4 {
+            param.mat[0][col] *= sx;
+            param.mat[1][col] *= sy;
+        }
+        param.xsize = width;
+        param.ysize = height;
+
+        let param_lt = Arc::new(ARParamLT::new_basic(param));
+        let backend = RustFreakMatcher::new(width, height)
+            .map_err(|e| JsValue::from_str(&format!("Failed to create FREAK matcher: {:?}", e)))?;
+        let handle = KpmHandle::new(width, height, Some(param_lt), Box::new(backend));
+
+        Ok(WasmKpmHandle {
+            handle,
+            width,
+            height,
+            loaded: false,
+        })
+    }
+
+    /// Load NFT reference data from `.fset3` bytes (KPM reference keypoints).
+    /// All pages are remapped to page 0 (single-marker setup).
+    pub fn load_ref_data(&mut self, fset3_bytes: &[u8]) -> Result<(), JsValue> {
+        let mut ref_data = KpmRefDataSet::load_from_bytes(fset3_bytes)
+            .map_err(|e| JsValue::from_str(&format!("Failed to load .fset3: {}", e)))?;
+        ref_data.change_page_no(KPM_CHANGE_PAGE_NO_ALL_PAGES, 0);
+        self.handle
+            .set_ref_data_set(ref_data)
+            .map_err(|e| JsValue::from_str(&format!("Failed to set ref data: {:?}", e)))?;
+        self.loaded = true;
+        Ok(())
+    }
+
+    /// Run KPM detection on an RGBA frame (`width * height * 4` bytes, e.g. a
+    /// canvas `ImageData.data` buffer).
+    ///
+    /// Returns `{ pose: number[12], page, error }` on a match, or `null` if no
+    /// marker was found.
+    pub fn detect(&mut self, rgba_bytes: &[u8]) -> Result<JsValue, JsValue> {
+        if !self.loaded {
+            return Err(JsValue::from_str(
+                "reference data not loaded — call load_ref_data first",
+            ));
+        }
+        let expected = (self.width * self.height * 4) as usize;
+        if rgba_bytes.len() != expected {
+            return Err(JsValue::from_str(&format!(
+                "rgba length {} != expected {} ({}x{}x4)",
+                rgba_bytes.len(),
+                expected,
+                self.width,
+                self.height
+            )));
+        }
+
+        let luma = rgba_to_gray(rgba_bytes);
+        self.handle
+            .kpm_matching(&luma)
+            .map_err(|e| JsValue::from_str(&format!("kpm_matching failed: {:?}", e)))?;
+
+        match self.handle.get_pose() {
+            Some((cam_pose, page, error)) => {
+                let mut pose = [0f32; 12];
+                for (r, row) in cam_pose.iter().enumerate() {
+                    pose[r * 4..r * 4 + 4].copy_from_slice(row);
+                }
+                let result = KpmDetectResult { pose, page, error };
+                serde_wasm_bindgen::to_value(&result)
+                    .map_err(|e| JsValue::from_str(&format!("serialize failed: {}", e)))
+            }
+            None => Ok(JsValue::NULL),
+        }
+    }
+
+    /// Whether reference data has been loaded.
+    pub fn is_loaded(&self) -> bool {
+        self.loaded
+    }
+}

crates/wasm/tests/kpm_detection.rs

@@ -0,0 +1,79 @@
+/*
+ *  kpm_detection.rs
+ *  WebARKitLib-rs
+ *
+ *  This file is part of WebARKitLib-rs - WebARKit.
+ *
+ *  WebARKitLib-rs is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU Lesser General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  WebARKitLib-rs is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU Lesser General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Lesser General Public License
+ *  along with WebARKitLib-rs.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ *  As a special exception, the copyright holders of this library give you
+ *  permission to link this library with independent modules to produce an
+ *  executable, regardless of the license terms of these independent modules, and to
+ *  copy and distribute the resulting executable under terms of your choice,
+ *  provided that you also meet, for each linked independent module, the terms and
+ *  conditions of the license of that module. An independent module is a module
+ *  which is neither derived from nor based on this library. If you modify this
+ *  library, you may extend this exception to your version of the library, but you
+ *  are not obligated to do so. If you do not wish to do so, delete this exception
+ *  statement from your version.
+ *
+ *  Copyright 2026 WebARKit.
+ *
+ *  Author(s): Walter Perdan @kalwalt https://github.com/kalwalt
+ *
+ */
+
+//! Headless wasm-bindgen tests for the KPM detection binding (#161).
+//!
+//! Run with: `wasm-pack test --node` (or `--headless --chrome`) from
+//! `crates/wasm`. These exercise `WasmKpmHandle` in a real wasm runtime —
+//! construction (camera-param parse + FREAK matcher init) and reference-data
+//! loading from in-memory `.fset3` bytes (`KpmRefDataSet::load_from_bytes`).
+//!
+//! Full `detect()` is covered end-to-end by the native `simple_nft` pipeline
+//! (same pure-Rust code) and the browser demo (`www/simple_nft_example.html`);
+//! it needs a decoded RGBA frame, out of scope for this lightweight runtime
+//! check.
+
+#![cfg(target_arch = "wasm32")]
+
+use wasm_bindgen_test::*;
+use webarkitlib_wasm::WasmKpmHandle;
+
+/// Demo assets, baked into the test binary.
+const CAMERA_PARA: &[u8] = include_bytes!("../www/assets/camera_para.dat");
+const PINBALL_FSET3: &[u8] = include_bytes!("../www/assets/pinball.fset3");
+
+#[wasm_bindgen_test]
+fn kpm_handle_constructs_and_loads_ref_data() {
+    let mut handle =
+        WasmKpmHandle::new(CAMERA_PARA, 640, 480).expect("WasmKpmHandle::new should succeed");
+    assert!(!handle.is_loaded(), "should start unloaded");
+
+    handle
+        .load_ref_data(PINBALL_FSET3)
+        .expect("load_ref_data should parse the .fset3 bytes");
+    assert!(handle.is_loaded(), "should be loaded after load_ref_data");
+}
+
+#[wasm_bindgen_test]
+fn detect_before_load_errors() {
+    let mut handle = WasmKpmHandle::new(CAMERA_PARA, 4, 4).expect("new");
+    // 4x4x4 RGBA; detection must refuse before reference data is loaded.
+    let rgba = [0u8; 4 * 4 * 4];
+    assert!(
+        handle.detect(&rgba).is_err(),
+        "detect should error before load_ref_data"
+    );
+}