@broberg/bodymap 0.3.0 → 0.4.0

package/dist/three.d.cts

@@ -31,6 +31,40 @@ interface RegionSetting {
 }
 /** Per-app config keyed by region key. An absent key ⇒ visible + selectable. */
 type RegionConfig = Record<string, RegionSetting>;
+/**
+ * What a pick on a region should DO (F052.20).
+ *
+ * Lives in the core because the 2D and 3D renderers share no click code, and a
+ * rule written twice is a rule that drifts. This repo measured the cost of that
+ * twice on 2026-08-28 alone: a fix applied to one half of a pair, and a sibling
+ * branch that carried the same defect with no test on it.
+ *
+ *   "clear"   the region is already marked → picking it again removes the mark
+ *   "select"  unmarked → open it for marking
+ *   "ignore"  not selectable (read-only or config) → nothing happens
+ *
+ * Three outcomes, not a boolean: "nothing happened because it is locked" and
+ * "nothing happened because we removed the mark" must never look alike to a
+ * caller.
+ */
+type PickOutcome = "clear" | "select" | "ignore";
+/**
+ * What a pick did, handed to the consuming app so it can make a sound or a buzz.
+ *
+ * The outcome is the one `decidePick` ACTUALLY returned, never the intent to tap
+ * — so a tap on a locked region can not announce itself as a removal, and a tap
+ * the pan/pinch guard swallowed emits nothing at all (it never gets here).
+ *
+ * It deliberately reuses `PickOutcome` rather than introducing a second
+ * three-word vocabulary. Two enums meaning the same thing is a drift bug waiting
+ * for the first person who adds a fourth outcome to only one of them.
+ */
+interface FeedbackSignal {
+    outcome: PickOutcome;
+    /** The region key that was picked. */
+    region: string;
+}
+type FeedbackFn = (signal: FeedbackSignal) => void;
 /** Colour control for the body renderers. Consumers pass a palette to theme the
  *  body base colour, the hover + selected highlights, the pain-heat colours, and
  *  optional per-region base colours. All values are CSS/hex colour strings. */
@@ -182,6 +216,15 @@ interface BodyMap3DProps {
      *  (default true). Set false for a patient/employee-facing flow where the code is
      *  internal jargon and the readable region name is enough. */
     showRegionCode?: boolean;
+    /** Fired after every pick with what ACTUALLY happened (F052.22): "select",
+     *  "clear" or "ignore". Wire it to a sound (`@broberg/soundkit`) or to native
+     *  haptics (Capacitor `Haptics.impact()` — the only route to a real buzz on an
+     *  iPhone, where web vibration does not exist). */
+    onFeedback?: FeedbackFn;
+    /** Web vibration on select/clear. Default true; silently inert where
+     *  `navigator.vibrate` is absent (every browser on iPhone, most desktops).
+     *  Set false to keep the signal but drop the buzz. */
+    haptics?: boolean;
     className?: string;
 }
 declare function BodyMap3D(props: BodyMap3DProps): react.JSX.Element;

package/dist/three.d.ts

@@ -31,6 +31,40 @@ interface RegionSetting {
 }
 /** Per-app config keyed by region key. An absent key ⇒ visible + selectable. */
 type RegionConfig = Record<string, RegionSetting>;
+/**
+ * What a pick on a region should DO (F052.20).
+ *
+ * Lives in the core because the 2D and 3D renderers share no click code, and a
+ * rule written twice is a rule that drifts. This repo measured the cost of that
+ * twice on 2026-08-28 alone: a fix applied to one half of a pair, and a sibling
+ * branch that carried the same defect with no test on it.
+ *
+ *   "clear"   the region is already marked → picking it again removes the mark
+ *   "select"  unmarked → open it for marking
+ *   "ignore"  not selectable (read-only or config) → nothing happens
+ *
+ * Three outcomes, not a boolean: "nothing happened because it is locked" and
+ * "nothing happened because we removed the mark" must never look alike to a
+ * caller.
+ */
+type PickOutcome = "clear" | "select" | "ignore";
+/**
+ * What a pick did, handed to the consuming app so it can make a sound or a buzz.
+ *
+ * The outcome is the one `decidePick` ACTUALLY returned, never the intent to tap
+ * — so a tap on a locked region can not announce itself as a removal, and a tap
+ * the pan/pinch guard swallowed emits nothing at all (it never gets here).
+ *
+ * It deliberately reuses `PickOutcome` rather than introducing a second
+ * three-word vocabulary. Two enums meaning the same thing is a drift bug waiting
+ * for the first person who adds a fourth outcome to only one of them.
+ */
+interface FeedbackSignal {
+    outcome: PickOutcome;
+    /** The region key that was picked. */
+    region: string;
+}
+type FeedbackFn = (signal: FeedbackSignal) => void;
 /** Colour control for the body renderers. Consumers pass a palette to theme the
  *  body base colour, the hover + selected highlights, the pain-heat colours, and
  *  optional per-region base colours. All values are CSS/hex colour strings. */
@@ -182,6 +216,15 @@ interface BodyMap3DProps {
      *  (default true). Set false for a patient/employee-facing flow where the code is
      *  internal jargon and the readable region name is enough. */
     showRegionCode?: boolean;
+    /** Fired after every pick with what ACTUALLY happened (F052.22): "select",
+     *  "clear" or "ignore". Wire it to a sound (`@broberg/soundkit`) or to native
+     *  haptics (Capacitor `Haptics.impact()` — the only route to a real buzz on an
+     *  iPhone, where web vibration does not exist). */
+    onFeedback?: FeedbackFn;
+    /** Web vibration on select/clear. Default true; silently inert where
+     *  `navigator.vibrate` is absent (every browser on iPhone, most desktops).
+     *  Set false to keep the signal but drop the buzz. */
+    haptics?: boolean;
     className?: string;
 }
 declare function BodyMap3D(props: BodyMap3DProps): react.JSX.Element;

package/dist/three.js

@@ -62,6 +62,25 @@ function isSelectable(key, config = {}) {
   if (s?.visible === false) return false;
   return s?.selectable ?? true;
 }
+var VIBRATION_PATTERNS = {
+  select: [12],
+  clear: [8, 40, 8],
+  ignore: []
+};
+function requestVibration(pattern, nav = globalThis.navigator) {
+  if (pattern.length === 0) return "skipped";
+  if (typeof nav?.vibrate !== "function") return "unsupported";
+  try {
+    return nav.vibrate([...pattern]) ? "requested" : "declined";
+  } catch {
+    return "declined";
+  }
+}
+function emitFeedback(outcome, region, opts = {}) {
+  opts.onFeedback?.({ outcome, region });
+  if (opts.haptics === false) return "skipped";
+  return requestVibration(VIBRATION_PATTERNS[outcome], opts.nav);
+}
 var defaultUi = {
   text: "#1e293b",
   mutedText: "#475569",
@@ -265,6 +284,8 @@ function BodyMap3D(props) {
     autoRotate = true,
     canvasHeight = "60vh",
     showRegionCode = true,
+    onFeedback,
+    haptics,
     className
   } = props;
   const chrome = uiColors(palette);
@@ -585,6 +606,7 @@ function BodyMap3D(props) {
   };
   pickRef.current = (k) => {
     const what = decidePick(k, reportRef.current, configRef.current ?? {});
+    emitFeedback(what, k, { onFeedback, haptics });
     if (what === "clear") removePain(k);
     else if (what === "select") setSelected(k);
     return what;