@broberg/bodymap 0.2.8 → 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. */
@@ -138,6 +172,21 @@ interface BodyMap3DUiLabels {
     female: string;
     hoverHint: string;
 }
+/**
+ * How much of the RUNNER-UP region bleeds into this vertex (F052.21).
+ *
+ * Takes SQUARED distances — what the assignment loop already has.
+ *
+ *   ratio = d1 / (d1 + d2)   → 0 at the anchor · 0.5 where two anchors are equidistant
+ *
+ * Returns 0 well inside a region and rises to 0.5 exactly at the seam, so the
+ * nearest region ALWAYS dominates and a vertex can never be painted mostly as
+ * its neighbour. Smoothstepped, so the fade has no visible start line of its own.
+ *
+ * This is a look, not a contract: hit-testing never sees this number, and the
+ * PainReport is unchanged.
+ */
+declare function seamBlend(nearestSq: number, secondSq: number): number;
 interface BodyMap3DProps {
     /** URLs of the male/female body GLBs (you host them; reference GLBs ship under `@broberg/bodymap/models/`). */
     models: BodyMap3DModels;
@@ -167,8 +216,17 @@ 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;
 
-export { BodyMap3D, type BodyMap3DModels, type BodyMap3DProps, type BodyMap3DSex, type BodyMap3DUiLabels, serializeReport };
+export { BodyMap3D, type BodyMap3DModels, type BodyMap3DProps, type BodyMap3DSex, type BodyMap3DUiLabels, seamBlend, serializeReport };

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. */
@@ -138,6 +172,21 @@ interface BodyMap3DUiLabels {
     female: string;
     hoverHint: string;
 }
+/**
+ * How much of the RUNNER-UP region bleeds into this vertex (F052.21).
+ *
+ * Takes SQUARED distances — what the assignment loop already has.
+ *
+ *   ratio = d1 / (d1 + d2)   → 0 at the anchor · 0.5 where two anchors are equidistant
+ *
+ * Returns 0 well inside a region and rises to 0.5 exactly at the seam, so the
+ * nearest region ALWAYS dominates and a vertex can never be painted mostly as
+ * its neighbour. Smoothstepped, so the fade has no visible start line of its own.
+ *
+ * This is a look, not a contract: hit-testing never sees this number, and the
+ * PainReport is unchanged.
+ */
+declare function seamBlend(nearestSq: number, secondSq: number): number;
 interface BodyMap3DProps {
     /** URLs of the male/female body GLBs (you host them; reference GLBs ship under `@broberg/bodymap/models/`). */
     models: BodyMap3DModels;
@@ -167,8 +216,17 @@ 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;
 
-export { BodyMap3D, type BodyMap3DModels, type BodyMap3DProps, type BodyMap3DSex, type BodyMap3DUiLabels, serializeReport };
+export { BodyMap3D, type BodyMap3DModels, type BodyMap3DProps, type BodyMap3DSex, type BodyMap3DUiLabels, seamBlend, serializeReport };

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",
@@ -214,6 +233,17 @@ var ANCHORS = {
   foot_left: [-0.1, 0.02, 0.11],
   foot_right: [0.1, 0.02, 0.11]
 };
+var SEAM = 0.18;
+function seamBlend(nearestSq, secondSq) {
+  const d1 = Math.sqrt(nearestSq), d2 = Math.sqrt(secondSq);
+  const sum = d1 + d2;
+  if (!(sum > 0)) return 0;
+  const ratio = d1 / sum;
+  const t = (ratio - (0.5 - SEAM)) / SEAM;
+  if (t <= 0) return 0;
+  if (t >= 1) return 0.5;
+  return t * t * (3 - 2 * t) * 0.5;
+}
 var ANCHOR_KEYS = Object.keys(ANCHORS);
 for (const k of ANCHOR_KEYS) ANCHORS[k][0] = -ANCHORS[k][0];
 function mergeLabels(locale, overrides) {
@@ -254,6 +284,8 @@ function BodyMap3D(props) {
     autoRotate = true,
     canvasHeight = "60vh",
     showRegionCode = true,
+    onFeedback,
+    haptics,
     className
   } = props;
   const chrome = uiColors(palette);
@@ -356,6 +388,8 @@ function BodyMap3D(props) {
     let modelRoot = null;
     let bodyMesh = null;
     let vertexRegion = [];
+    let vertexNeighbour = [];
+    let vertexBlend = new Float32Array(0);
     let colorAttr = null;
     let hovered = null;
     const loader = new GLTFLoader();
@@ -367,14 +401,32 @@ function BodyMap3D(props) {
       if (selectedRef.current === key) return paletteRef.current.selected;
       return baseColorFor(key, paletteRef.current);
     };
-    const colorRegion = (key, hex) => {
+    const tmp2 = new THREE.Color();
+    const colourOf = (key) => hovered === key ? paletteRef.current.hover : restingHex(key);
+    const paint = () => {
       if (!colorAttr) return;
-      tmp.set(hex);
-      for (let i = 0; i < vertexRegion.length; i++) if (vertexRegion[i] === key) colorAttr.setXYZ(i, tmp.r, tmp.g, tmp.b);
+      const cache = /* @__PURE__ */ new Map();
+      const col = (k) => {
+        let c = cache.get(k);
+        if (!c) {
+          c = new THREE.Color(colourOf(k));
+          cache.set(k, c);
+        }
+        return c;
+      };
+      for (let i = 0; i < vertexRegion.length; i++) {
+        tmp.copy(col(vertexRegion[i]));
+        const w = vertexBlend[i];
+        if (w > 0) {
+          tmp2.copy(col(vertexNeighbour[i]));
+          tmp.lerp(tmp2, w);
+        }
+        colorAttr.setXYZ(i, tmp.r, tmp.g, tmp.b);
+      }
       colorAttr.needsUpdate = true;
     };
     const refresh = () => {
-      for (const k of ANCHOR_KEYS) colorRegion(k, hovered === k ? paletteRef.current.hover : restingHex(k));
+      paint();
       renderFrame();
     };
     const loadModel = (which) => {
@@ -403,18 +455,27 @@ function BodyMap3D(props) {
           const n = pos.count;
           const cols = new Float32Array(n * 3);
           vertexRegion = new Array(n);
+          vertexNeighbour = new Array(n);
+          vertexBlend = new Float32Array(n);
           const v = new THREE.Vector3();
           for (let i = 0; i < n; i++) {
             v.fromBufferAttribute(pos, i).applyMatrix4(bodyMesh.matrixWorld);
-            let best = 0, bd = Infinity;
+            let best = 0, second = 0, bd = Infinity, sd = Infinity;
             for (let a = 0; a < anchorVecs.length; a++) {
               const d = v.distanceToSquared(anchorVecs[a]);
               if (d < bd) {
+                sd = bd;
+                second = best;
                 bd = d;
                 best = a;
+              } else if (d < sd) {
+                sd = d;
+                second = a;
               }
             }
             vertexRegion[i] = ANCHOR_KEYS[best];
+            vertexNeighbour[i] = ANCHOR_KEYS[second];
+            vertexBlend[i] = seamBlend(bd, sd);
           }
           colorAttr = new THREE.BufferAttribute(cols, 3);
           geo.setAttribute("color", colorAttr);
@@ -474,10 +535,8 @@ function BodyMap3D(props) {
       if ((e.buttons || 0) !== 0) return;
       const k = pick(e.clientX, e.clientY);
       if (k === hovered) return;
-      const prev = hovered;
       hovered = k;
-      if (prev) colorRegion(prev, restingHex(prev));
-      if (k) colorRegion(k, paletteRef.current.hover);
+      paint();
       canvas.style.cursor = k ? "pointer" : "default";
       renderFrame();
     };
@@ -547,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;
@@ -586,6 +646,6 @@ function BodyMap3D(props) {
   ] });
 }
 
-export { BodyMap3D, serializeReport };
+export { BodyMap3D, seamBlend, serializeReport };
 //# sourceMappingURL=three.js.map
 //# sourceMappingURL=three.js.map