@broberg/bodymap 0.3.0 → 0.5.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,31 @@ 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;
+    /** Soften the colour transition between neighbouring regions (F052.21).
+     *
+     *  DEFAULT FALSE, and the default is the accessible one (F052.23). The blend
+     *  mixes the BODY colour into a marked region near its boundary — which on a
+     *  SMALL mark is most of the mark. Measured on a phone with a consumer's
+     *  palette and one knee marked: the mark's average contrast against the body
+     *  fell from 4.71:1 to 3.59:1, i.e. below the WCAG AA threshold of 4.5:1, on a
+     *  surface a public authority is legally required to meet.
+     *
+     *  At the single strongest pixel the cost is small (5.12 → 4.78) — which is
+     *  why a spot-check misses it and the AVERAGE is what a person sees.
+     *
+     *  Turn it on when the marked areas are LARGE and you have no accessibility
+     *  duty: the soft seam genuinely looks better there, and that is why it is
+     *  still here rather than deleted. */
+    seam?: 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,31 @@ 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;
+    /** Soften the colour transition between neighbouring regions (F052.21).
+     *
+     *  DEFAULT FALSE, and the default is the accessible one (F052.23). The blend
+     *  mixes the BODY colour into a marked region near its boundary — which on a
+     *  SMALL mark is most of the mark. Measured on a phone with a consumer's
+     *  palette and one knee marked: the mark's average contrast against the body
+     *  fell from 4.71:1 to 3.59:1, i.e. below the WCAG AA threshold of 4.5:1, on a
+     *  surface a public authority is legally required to meet.
+     *
+     *  At the single strongest pixel the cost is small (5.12 → 4.78) — which is
+     *  why a spot-check misses it and the AVERAGE is what a person sees.
+     *
+     *  Turn it on when the marked areas are LARGE and you have no accessibility
+     *  duty: the soft seam genuinely looks better there, and that is why it is
+     *  still here rather than deleted. */
+    seam?: 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,9 @@ function BodyMap3D(props) {
     autoRotate = true,
     canvasHeight = "60vh",
     showRegionCode = true,
+    onFeedback,
+    haptics,
+    seam = false,
     className
   } = props;
   const chrome = uiColors(palette);
@@ -302,6 +324,8 @@ function BodyMap3D(props) {
   const pickRef = useRef(() => "ignore");
   const setReadyRef = useRef(setReady);
   setReadyRef.current = setReady;
+  const seamRef = useRef(seam);
+  seamRef.current = seam;
   const apiRef = useRef(null);
   useEffect(() => {
     if (!webglAvailable()) {
@@ -395,7 +419,7 @@ function BodyMap3D(props) {
       };
       for (let i = 0; i < vertexRegion.length; i++) {
         tmp.copy(col(vertexRegion[i]));
-        const w = vertexBlend[i];
+        const w = seamRef.current ? vertexBlend[i] : 0;
         if (w > 0) {
           tmp2.copy(col(vertexNeighbour[i]));
           tmp.lerp(tmp2, w);
@@ -429,7 +453,7 @@ function BodyMap3D(props) {
         });
         if (bodyMesh) {
           const geo = bodyMesh.geometry;
-          geo.computeVertexNormals();
+          if (!geo.getAttribute("normal")) geo.computeVertexNormals();
           const pos = geo.getAttribute("position");
           const n = pos.count;
           const cols = new Float32Array(n * 3);
@@ -566,7 +590,7 @@ function BodyMap3D(props) {
   }, []);
   useEffect(() => {
     apiRef.current?.refresh();
-  }, [selected, report, palette]);
+  }, [selected, report, palette, seam]);
   const sexInited = useRef(false);
   useEffect(() => {
     if (!sexInited.current) {
@@ -585,6 +609,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;