pipwave-ekyc-uikit 3.1.4-beta.1 → 3.2.0

package/.claude/commands/release-message.md

@@ -0,0 +1,47 @@
+---
+description: Write a release message for the current branch's changes in our house style
+argument-hint: <Fix|Enhancement|New> [target-branch] [--short]
+---
+
+Write a release message for the changes on the CURRENT branch, which are merging
+into a target branch. Do not repeat prompting overhead back to me — just produce
+the message.
+
+## Inputs (from "$ARGUMENTS")
+- **Type** (required): one of `Fix`, `Enhancement`, `New` (case-insensitive; also accept `Fixes`).
+- **Target branch** (optional): the branch these changes merge INTO. Default `origin/master`.
+- **`--short`** (optional flag): also/instead produce a tighter one-liner.
+
+If the type is missing or ambiguous, ask me once; otherwise proceed without questions.
+
+## Steps
+1. Resolve the target branch (default `origin/master`). Run:
+   - `git log <target>..HEAD --oneline --no-merges`
+   - `git diff <target>...HEAD --stat`
+   - `git diff <target>...HEAD -- <the changed source files>` (skip `dist/`, lockfiles, version-only bumps)
+2. Read the actual source diff to understand the real user/merchant-facing impact — do not
+   paraphrase the commit subject; describe what changed and why it matters to the user.
+3. Pull the Shortcut ID (`sc-XXXXXX`) from the branch name or commit subjects.
+4. Output ONE sentence (may use commas/clauses), prefixed with `[sc-XXXXXX]`.
+
+## House style by type
+
+**Fix** — state the symptom that was broken, then the fix.
+Open with "Fixed" or "Fixes".
+> [sc-338198] Fixed selfie auto-capturing off-center or too-close faces by adding real-time centering and distance guards that block capture until the face is properly framed.
+
+**Enhancement** — improves existing behavior. Open with an action verb ("Changed",
+"Increased", "Skipped") or "<feature> now ...".
+> [sc-326139] Increased camera capture area size to enhance resolution of submitted document images.
+
+**New** — a brand-new capability. Open with "Introduced", "Added", or "Implemented".
+> [sc-334995] Real-time card edge detection that automatically captures the document the moment its edges are properly aligned within the frame, with live on-screen feedback so users no longer have to tap the capture button themselves.
+
+## Tone rules
+- User/merchant-facing outcome first, mechanism second. Not a changelog of files touched.
+- One sentence. Concrete (name the feature/page/behavior), not abstract.
+- No em dash "—"; use a colon or comma.
+- No bold, headers, emoji, or bullet lists in the message itself.
+- If `--short`, also give a tighter variant that keeps the `[sc-XXXXXX]` prefix and the core outcome.
+
+After the message, offer light follow-ups (shorter version, different type framing) rather than over-producing.

package/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(node_modules/.bin/vitest run *)",
+      "Bash(ls -la CLAUDE.md .claude/)",
+      "Bash(ls .claude/commands)",
+      "Bash(ls .claude/skills)"
+    ]
+  }
+}

package/CODE_REVIEW_sc-345185.md

@@ -0,0 +1,102 @@
+# 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.

package/package.json

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