pipwave-ekyc-uikit 3.2.1 → 3.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pipwave-ekyc-uikit",
-  "version": "3.2.1",
+  "version": "3.2.2",
   "description": "",
   "main": "dist/pw-bundle.js",
   "module": "dist/pw-bundle.mjs",

package/CODE_REVIEW_sc-345185.md

@@ -1,102 +0,0 @@
-# Code Review — `feature-teojunjie-sc-345185-fix-face-detection-deadlock`
-
-**Base:** `origin/master` · **Head:** `61f7559`
-**Scope:** `src/plugins/face-detection.ts` (+105/-22), `src/plugins/face-detection.test.ts` (new, +227)
-
-Two commits: (1) fix selfie face-detection deadlock + hint flicker via a per-frame
-position-hint debounce (`confirmPositionState`) and one-sided top-containment slack;
-(2) apply the forehead-overestimate correction to the fill-ratio checks too
-(`FACE_HEIGHT_MULTIPLIER` 1.6 → 1.3).
-
-The debounce logic, the `disableDetection`/reset wiring, and the cross-file surface
-all check out — every changed method and event name is private to the SDK, and the
-public `listenTo*` callback contracts are unchanged, so no external caller breaks.
-
----
-
-## Findings
-
-### 1. Shipped failing test — `isFaceDetected` top-overflow guard is not actually enforced (CONFIRMED, high)
-
-**File:** [src/plugins/face-detection.test.ts:72](src/plugins/face-detection.test.ts#L72) (root cause in [src/plugins/face-detection.ts:34](src/plugins/face-detection.ts#L34) / [:248](src/plugins/face-detection.ts#L248))
-
-The new test `"still rejects a face with a genuine top overflow beyond estimate noise"`
-asserts `isFaceDetected(pos)` is `false`, but it returns `true`. **`vitest run` fails
-(1 failed / 7 passed).**
-
-The test face has top landmark `y = 68`, `h = 170`. The new top check is:
-
-```
-withinTop = posFace.y - foreheadPadding > posCircle.y - topSlack
-          = 68 - (170*0.6) > 0 - (170*0.3)
-          = 68 - 102 > -51
-          = -34 > -51   → true   (face accepted)
-```
-
-Reducing to the effective requirement: `posFace.y > posCircle.y + 0.3*h`. The `0.3`
-slack cancels half of the `0.6` forehead padding, so the top-containment guard only
-requires ~0.3h of forehead clearance, not 0.6h. The face the author considered a
-"genuine top crop" (`y=68`) still passes.
-
-This is two problems in one:
-- **CI is red** — a failing test is being committed.
-- The comment at [:32-33](src/plugins/face-detection.ts#L32-L33) claims "a genuine top
-  crop (well beyond estimate noise) still fails" — the test demonstrates it does not.
-  Either `TOP_CONTAINMENT_SLACK_RATIO` (0.3) is too large, or the test's coordinates
-  are wrong. Decide which behavior is intended and align code + test.
-
-**Failure scenario:** run `npm test`; the suite fails. In production, a face whose top
-sits well above the intended forehead margin is accepted as "in frame".
-
----
-
-### 2. `TOP_CONTAINMENT_SLACK_RATIO` comment does not match its value (low, maintainability)
-
-**File:** [src/plugins/face-detection.ts:30-34](src/plugins/face-detection.ts#L30-L34)
-
-The comment justifies the constant as "~0.1 covers the padding's average-case
-overestimate (0.6 - 0.5); the rest is margin," but the value is `0.3` — i.e. 0.1 of
-correction and 0.2 of pure leniency. Because this same 0.3 is also what defeats half
-the forehead padding (finding #1) and is folded into `FACE_HEIGHT_MULTIPLIER = 1 + 0.6
-- 0.3 = 1.3`, the effective assumption becomes "forehead ≈ 0.3h" everywhere. That is
-internally consistent, but the stated reasoning (overestimate is only ~0.1) argues for
-a much smaller slack. Reconcile the comment with the number so the next tuner isn't
-misled about how much margin is deliberate.
-
----
-
-### 3. Sustained oscillation between two failing position states can strand a stale hint (PLAUSIBLE, low)
-
-**File:** [src/plugins/face-detection.ts:402-412](src/plugins/face-detection.ts#L402-L412)
-
-`confirmPositionState` resets `candidatePositionCount` to 1 whenever the candidate
-differs from the previous frame. If two *different* failing checks alternate every
-frame (e.g. `faceTooClose` ↔ `faceTooFar` near their thresholds), neither ever reaches
-`STABLE_FRAMES_TO_CHANGE_POSITION = 2`, so no new hint is emitted and `lastHintEvent`
-stays at whatever was shown last — potentially a stale smile-stage prompt
-(`userNoSmile`) while the face is actually mispositioned.
-
-**Failure scenario:** user hovers at a distance where jitter flips between "too close"
-and "too far" frame-to-frame; the on-screen guidance freezes on the previous message
-instead of prompting a correction. Lower likelihood (jitter usually stays in one
-category), but worth a bounded fallback if observed in the field.
-
----
-
-### 4. Formatting nits (trivial)
-
-**File:** [src/plugins/face-detection.ts:413](src/plugins/face-detection.ts#L413), [:417](src/plugins/face-detection.ts#L417)
-
-- Line 413 has trailing whitespace.
-- Missing blank lines between `confirmPositionState`, `resetPositionDebounce`, and
-  `checkFace` (methods run together). Cosmetic; align with the spacing used elsewhere
-  in the class.
-
----
-
-## Verification performed
-
-- `vitest run src/plugins/face-detection.test.ts` under Node 22 → **1 failed, 7 passed**
-  (finding #1 reproduced directly).
-- Cross-file caller trace (`uisdk.ts`, `face-camera.ts`): no signature/contract breakage;
-  only hint timing/thresholds shift, as intended.