Add direct-manipulation UI: drag on the 3D head to drive the controls

README.md

@@ -52,6 +52,30 @@ no camera reset and no flicker.
 The model is pure NumPy (a few matrix multiplies, ~40 ms per evaluation), so the
 Space runs on `cpu-basic` with no GPU required.
 
+## Direct manipulation
+
+You can also **grab the 3D head directly** instead of only moving sliders — hover
+any region to see what it does (the head is colour-coded by control region):
+
+- **Eye** — drag ↕ to open / close that eye, ↔ to glance (aim the eyes).
+- **Mouth** — drag the centre / chin **down** to open the jaw; drag a **lip
+  corner outward** to smile / stretch.
+- **Tongue** — drag down to stick it out.
+- **Skull / forehead** — drag to turn & nod the head; **gaze** aims when you grab
+  an eyeball.
+- **Ear** — drag in / out (drives *Head shape 8*); **Cheek** — drag to stretch
+  the face (drives *Head shape 7*).
+- **Alt + drag** free-sculpts the surface under the cursor with a soft falloff
+  brush (nose, brow, jawline). These are geometric offsets on top of the model —
+  a **↺ Reset shaping** button clears them.
+- **Shift + drag** repositions the head, **right-drag** (or drag empty space)
+  orbits the camera, **scroll** zooms.
+
+Each region drives the very same slider(s) — hovering one glows the matching
+control and its tab — so the sliders and the head stay in sync. Every gesture
+runs through the same reactive pipeline as the sliders; slider-driving drags are
+throttled and run off the queue so the mesh tracks the cursor in real time.
+
 ## Credits
 
 Model and reference demo: [google/GNM](https://github.com/google/GNM),

app.py

@@ -140,6 +140,122 @@ NUM_TRANSLATION = 3
 TOTAL_SLIDERS = NUM_IDENTITY + NUM_EXPRESSION + NUM_POSE + NUM_TRANSLATION
 
 
+# ---------------------------------------------------------------------------
+# Direct-manipulation zones.
+#
+# The viewer lets you click-and-drag *on the head itself* to drive the sliders:
+# grab the jaw and pull down to open the mouth, grab an eyeball to aim the
+# gaze, grab the head shell to turn it, etc. To do that, every mesh vertex is
+# tagged with an interaction "zone", and the viewer maps a drag over a zone to
+# the matching slider change. The tags are derived from GNM's own semantic
+# vertex groups (chin_region, left_orbital_region, left_eye, ...), so the
+# mapping tracks the real anatomy of the model.
+# ---------------------------------------------------------------------------
+(
+    ZONE_HEAD,         # 0 - skull / forehead / nose: rotate the head
+    ZONE_LEFT_EYE,     # 1 - left lid+brow skin: open/close left eye
+    ZONE_RIGHT_EYE,    # 2 - right lid+brow skin: open/close right eye
+    ZONE_LEFT_GAZE,    # 3 - left eyeball: aim gaze
+    ZONE_RIGHT_GAZE,   # 4 - right eyeball: aim gaze
+    ZONE_MOUTH_OPEN,   # 5 - centre lips + chin: drag to open / close the jaw
+    ZONE_TONGUE,       # 6 - tongue / teeth: push the tongue out
+    ZONE_MOUTH_SMILE,  # 7 - lip corners: drag outward to smile / stretch
+    ZONE_EAR,          # 8 - ears: drag to pull them in / out (free sculpt)
+    ZONE_CHEEK,        # 9 - cheeks: drag to stretch the face (free sculpt)
+) = range(10)
+
+_zones = np.zeros(NUM_VERTICES, dtype=np.int16)  # default: ZONE_HEAD
+
+# Neutral vertex positions, for splitting the mouth into centre (open) vs
+# corner (smile) sub-zones by x-coordinate.
+_NEUTRAL = np.asarray(GNM(None, None, None, None))
+
+
+def _tag_zone(regions, zone):
+    """Tag every vertex of the named GNM vertex groups with `zone`."""
+    for r in regions:
+        if r in GNM.vertex_group_names:
+            _zones[np.asarray(GNM.vertex_group_indices(r))] = zone
+
+
+# Applied low-priority first; later tags win where regions overlap. Eyeballs
+# (gaze) are tagged last so grabbing the eye always aims it rather than blinks.
+_tag_zone(
+    ["upper_lip", "lower_lip", "mouth_sock",
+     "upper_lip_region", "lower_lip_region", "chin_region"],
+    ZONE_MOUTH_OPEN,
+)
+_tag_zone(["tongue", "gums", "teeth"], ZONE_TONGUE)
+_tag_zone(
+    ["left_brow_region", "left_orbital_region", "left_infraorbital_region"],
+    ZONE_LEFT_EYE,
+)
+_tag_zone(
+    ["right_brow_region", "right_orbital_region", "right_infraorbital_region"],
+    ZONE_RIGHT_EYE,
+)
+_tag_zone(["left_eye"], ZONE_LEFT_GAZE)
+_tag_zone(["right_eye"], ZONE_RIGHT_GAZE)
+# Ears and cheeks are free-sculpt handles (drag to reshape geometrically).
+_tag_zone(["ears"], ZONE_EAR)
+_tag_zone(
+    ["left_cheek_region", "right_cheek_region",
+     "left_zygomatic_region", "right_zygomatic_region"],
+    ZONE_CHEEK,
+)
+
+# Split the mouth: lip vertices near the corners (|x| beyond ~half the mouth
+# half-width) become the SMILE zone; the central lips + chin stay OPEN. This
+# gives two separately-highlighted mouth areas that each do one thing.
+_lip_groups = ["upper_lip", "lower_lip", "upper_lip_region", "lower_lip_region"]
+_lip_idx = np.unique(np.concatenate(
+    [np.asarray(GNM.vertex_group_indices(g)) for g in _lip_groups
+     if g in GNM.vertex_group_names]
+))
+_corner_x = 0.6 * np.abs(_NEUTRAL[_lip_idx, 0]).max()   # corner threshold
+_corner_verts = _lip_idx[np.abs(_NEUTRAL[_lip_idx, 0]) >= _corner_x]
+_zones[_corner_verts] = ZONE_MOUTH_SMILE
+
+ZONES_JSON = json.dumps(_zones.tolist(), separators=(",", ":"))
+
+# Start offset of each slider group within its category's flat slider list
+# (the assembled slider lists are in this canonical order).
+_EXPR_SLOT_START = {}
+_c = 0
+for _name, _g in EXPRESSION_GROUPS.items():
+    _EXPR_SLOT_START[_name] = _c
+    _c += len(_g)
+_POSE_SLOT_START = {}
+_c = 0
+for _joint, _lim in POSE_LIMITS.items():
+    _POSE_SLOT_START[_joint] = _c
+    _c += len(_lim)
+
+# Which specific slider each drag gesture drives, addressed by the registry
+# key baked into that slider (see `_vslider`). Measured directions on this
+# model (see the calibration in the module docstring / presets):
+#   mouth slot 0 (lower_face_region_000): +raises/closes, -drops jaw open
+#   left/right eye slot 0: + raises brow / widens, - lowers / closes
+#   tongue slot +1 (tongue_000): + pushes the tongue forward/out
+#   head pose: pitch = nod, yaw = turn; gaze pose: pitch/yaw aim the eyes
+VIEWER_CFG = {
+    "leftEyeKey":  f"ex_{_EXPR_SLOT_START['Left eye']}",
+    "rightEyeKey": f"ex_{_EXPR_SLOT_START['Right eye']}",
+    "mouthKey":    f"ex_{_EXPR_SLOT_START['Mouth']}",
+    # lower_face_region_001: negative widens + lifts the mouth corners (smile /
+    # stretch), positive puckers. Horizontal mouth drags map to this.
+    "smileKey":    f"ex_{_EXPR_SLOT_START['Mouth'] + 1}",
+    "tongueKey":   f"ex_{_EXPR_SLOT_START['Tongue'] + 1}",
+    "headPitchKey": f"pose_{_POSE_SLOT_START['head'] + 0}",
+    "headYawKey":   f"pose_{_POSE_SLOT_START['head'] + 1}",
+    "gazePitchKey": f"pose_{_POSE_SLOT_START['gaze'] + 0}",
+    "gazeYawKey":   f"pose_{_POSE_SLOT_START['gaze'] + 1}",
+    "txKey": "tr_0",
+    "tyKey": "tr_1",
+}
+VIEWER_CFG_JSON = json.dumps(VIEWER_CFG, separators=(",", ":"))
+
+
 # ---------------------------------------------------------------------------
 # Parameter assembly + mesh generation.
 # ---------------------------------------------------------------------------
@@ -210,6 +326,58 @@ def positions_json(*slider_values) -> str:
     return json.dumps(flat, separators=(",", ":"))
 
 
+# ---------------------------------------------------------------------------
+# Sculpt (free-pull) — drag a point on the mesh to reshape the head.
+#
+# The bind-pose is linear in identity: vertex_v = template_v + Σ_k id_k · B[k,v]
+# (B = vertex_identity_basis). So the Jacobian of the grabbed vertex w.r.t. the
+# 10 exposed head-shape sliders is a constant (3, 10) matrix. Given a world-
+# space drag `d` at vertex `vi`, we solve the (under-determined) least-squares
+# `A·Δ ≈ d` for the smallest slider change Δ that moves that point toward the
+# drag, add it to the sliders the drag started from, and clip to range. Because
+# the basis is rich, the min-norm solution stays reasonably local (pulling an
+# ear pokes the ear; pulling a cheek widens the face).
+# ---------------------------------------------------------------------------
+_ID_JAC = np.asarray(GNM.vertex_identity_basis)[IDENTITY_INDICES].astype(np.float64)  # (10, V, 3)
+
+# Gain for the sculpt gradient step (see sculpt_pull). Chosen so a moderate
+# Alt-drag produces a clear but un-maxed reshape.
+_SCULPT_GAIN = 6000.0
+
+
+def sculpt_pull(payload, *slider_values):
+    """Reshape the head by nudging the shape sliders toward a drag.
+
+    `payload` is a JSON string ``{"vi": int, "d": [dx,dy,dz], "base": [10]}``
+    set by the viewer during an Alt-drag: `vi` is the grabbed vertex, `d` the
+    cumulative world drag, `base` the identity slider values at drag start.
+
+    The 10 exposed identity modes are *global* head-shape PCA directions, so a
+    single point can't be pulled to an arbitrary place (that inverse is
+    ill-conditioned). Instead we take a bounded gradient step: move each shape
+    slider proportionally to how strongly it pushes the grabbed vertex along
+    the drag (``Δ_k = gain · B[k, vi] · d``). Well-covered regions (cheeks,
+    brow, jaw) respond strongly; areas the basis barely controls (nose tip)
+    move a little — it never blows up. Returns the new identity slider values.
+    """
+    cur = [float(v) for v in slider_values[:NUM_IDENTITY]]
+    if not payload:
+        return cur
+    try:
+        p = json.loads(payload)
+        vi = int(p["vi"])
+        d = np.asarray(p["d"], dtype=np.float64).reshape(3)
+        base = np.asarray(p.get("base", cur), dtype=np.float64).reshape(-1)[:NUM_IDENTITY]
+    except Exception:
+        return cur
+    if not (0 <= vi < _ID_JAC.shape[1]):
+        return cur
+    step = _SCULPT_GAIN * (_ID_JAC[:, vi, :] @ d)   # (10,) gradient of vertex·drag
+    new = np.clip(base + step, -3.0, 3.0)
+    new = np.round(new / 0.05) * 0.05               # snap to the slider step
+    return [float(x) for x in new]
+
+
 # ---------------------------------------------------------------------------
 # Categorical / keyword expression presets.
 #
@@ -323,7 +491,20 @@ VIEWER_TEMPLATE = (
     '<div id="gnm-wrap" style="width:100%;height:560px;border-radius:8px;'
     'overflow:hidden;background:#f0f0f0;position:relative;">'
     '<canvas id="gnm-canvas" style="width:100%;height:100%;display:block;">'
-    "</canvas></div>"
+    "</canvas>"
+    # Hover hint: shows what dragging the region under the cursor will do.
+    '<div id="gnm-hint" style="position:absolute;top:10px;left:10px;'
+    "padding:4px 10px;border-radius:6px;background:rgba(0,0,0,0.62);"
+    "color:#fff;font-size:13px;font-weight:600;letter-spacing:.2px;"
+    'pointer-events:none;opacity:0;transition:opacity .12s;z-index:5;">'
+    "</div>"
+    # Reset-shaping button: appears once you free-sculpt (ear/cheek/Alt-drag),
+    # since those geometric tweaks have no slider to reset. Clears the sculpt.
+    '<button id="gnm-clear-sculpt" style="position:absolute;top:10px;'
+    "right:10px;display:none;padding:4px 10px;border-radius:6px;border:none;"
+    "background:rgba(0,0,0,0.62);color:#fff;font-size:12px;font-weight:600;"
+    'cursor:pointer;z-index:6;">↺ Reset shaping</button>'
+    "</div>"
 )
 
 # js_on_load runs exactly once on mount. It builds a persistent Three.js scene,
@@ -336,10 +517,102 @@ VIEWER_JS_ON_LOAD = """
 (function () {
   const FACES = __FACES__;
   const COLORS = __COLORS__;
+  const ZONES = __ZONES__;   // per-vertex interaction zone id
+  const CFG = __CFG__;        // gesture -> slider-registry-key map
   // GNM head geometry (meters): Y-up / +Z-forward, centered ~ (0, 0.24, 0).
   const TARGET = [0, 0.24, 0.02];
 
-  let renderer, scene, camera, geometry, mesh;
+  // Zone ids (mirror the Python ZONE_* constants).
+  const Z_HEAD=0, Z_LEYE=1, Z_REYE=2, Z_LGAZE=3, Z_RGAZE=4, Z_MOUTH=5,
+        Z_TONGUE=6, Z_SMILE=7, Z_EAR=8, Z_CHEEK=9;
+  // Zones whose plain drag free-sculpts the geometry (none now — ears & cheeks
+  // drive head-shape sliders instead; Alt+drag still free-sculpts anywhere).
+  const SCULPT_ZONES = {};
+
+  // Drag sensitivities (slider-units per pixel of drag).
+  const HEAD_G = 0.35;    // degrees / px  (head rotation)
+  const GAZE_G = 0.18;    // degrees / px  (eye gaze)
+  const EXPR_G = 0.022;   // blendshape units / px (eyes, mouth, tongue)
+  const TRANS_G = 0.0016; // meters / px   (shift-drag translate)
+  const ID_G = 0.02;      // head-shape units / px (ear / cheek -> identity)
+  const SCULPT_G = 1.0;   // sculpt drag is sent as real-world meters; the
+                          // response gain lives server-side in _SCULPT_GAIN
+
+  // What a drag over each zone does: a friendly label + the slider(s) it
+  // drives. axis 'x' = horizontal drag, 'y' = vertical drag (up is positive
+  // because screen-y grows downward and we negate it). sign flips direction.
+  function zoneSpec(z) {
+    switch (z) {
+      case Z_HEAD:  return { label: "↺  Rotate head · drag to turn / nod",
+        t: [ {key: CFG.headYawKey,   axis:'x', gain: HEAD_G, sign: +1},
+             {key: CFG.headPitchKey, axis:'y', gain: HEAD_G, sign: -1} ] };
+      // The eyeball sits slightly behind the lids, so from the front a click
+      // lands on the lid/brow. That eye zone therefore does both: drag ↕ to
+      // open/close *this* eye, drag ↔ to glance (gaze yaw, both eyes). Orbit
+      // round to grab the eyeball itself (Z_*GAZE) for full up/down aiming.
+      case Z_LEYE:  return { label: "👁  Left eye · ↕ open / close  ·  ↔ glance",
+        t: [ {key: CFG.leftEyeKey, axis:'y', gain: EXPR_G, sign: +1},
+             {key: CFG.gazeYawKey, axis:'x', gain: GAZE_G, sign: +1} ] };
+      case Z_REYE:  return { label: "👁  Right eye · ↕ open / close  ·  ↔ glance",
+        t: [ {key: CFG.rightEyeKey, axis:'y', gain: EXPR_G, sign: +1},
+             {key: CFG.gazeYawKey,  axis:'x', gain: GAZE_G, sign: +1} ] };
+      case Z_LGAZE:
+      case Z_RGAZE: return { label: "👀  Gaze · drag to aim the eyes",
+        t: [ {key: CFG.gazeYawKey,   axis:'x', gain: GAZE_G, sign: +1},
+             {key: CFG.gazePitchKey, axis:'y', gain: GAZE_G, sign: -1} ] };
+      // Centre of the mouth / chin: vertical drag only — pull the jaw down to
+      // open, push up to close.
+      case Z_MOUTH: return { label: "🗣  Jaw · drag down to open the mouth",
+        t: [ {key: CFG.mouthKey, axis:'y', gain: EXPR_G, sign: +1} ] };
+      // Lip corners: horizontal drag only — pull a corner outward to smile /
+      // stretch, push inward to pucker (outwardX resolves the side).
+      case Z_SMILE: return { label: "😀  Mouth corner · pull out to smile / stretch",
+        t: [ {key: CFG.smileKey, axis:'x', gain: 0.02, outwardX: true} ] };
+      case Z_TONGUE:return { label: "👅  Tongue · drag down to stick it out",
+        t: [ {key: CFG.tongueKey, axis:'y', gain: EXPR_G, sign: -1} ] };
+      // Ears & cheeks drive head-shape sliders (Head shape 8 / 7). outwardXPos:
+      // pulling the ear out raises id_7 (ears out); outwardX: pulling the cheek
+      // out lowers id_6 (fuller face). Both resolve their side from the grab.
+      case Z_EAR:   return { label: "👂  Ear · drag in / out (Head shape 8)",
+        t: [ {key: "id_7", axis:'x', gain: ID_G, outwardXPos: true} ] };
+      case Z_CHEEK: return { label: "🫦  Cheek · drag to stretch the face (Head shape 7)",
+        t: [ {key: "id_6", axis:'x', gain: ID_G, outwardX: true} ] };
+    }
+    return { label: "", t: [] };
+  }
+
+  // Highlight tints per zone (RGB 0..1). Head is not tinted (it's most of the
+  // mesh) — only the feature zones light up on hover.
+  const HL = {
+    1:[1.0,0.55,0.05], 2:[1.0,0.55,0.05], 3:[0.10,0.60,1.0],
+    4:[0.10,0.60,1.0], 5:[1.0,0.32,0.34], 6:[0.92,0.20,0.62],
+    7:[0.20,0.80,0.45],   // smile corners — distinct green from the red jaw
+    8:[0.65,0.45,1.0],    // ears — purple
+    9:[1.0,0.75,0.15],    // cheeks — amber
+  };
+
+  let renderer, scene, camera, geometry, mesh, colorAttr, clearBtn;
+  // Persistent free-sculpt offsets (world space), added on top of the GNM
+  // mesh every frame so a pulled ear / stretched cheek survives slider morphs.
+  let sculptOffsets = null, lastFlat = null;
+
+  // Show the "Reset shaping" button only when some sculpt offset is non-zero
+  // (those geometric tweaks aren't tied to any slider, so this is their reset).
+  function hasSculpt() {
+    if (!sculptOffsets) return false;
+    for (let i = 0; i < sculptOffsets.length; i++) if (sculptOffsets[i] !== 0) return true;
+    return false;
+  }
+  function updateClearBtn() {
+    if (clearBtn) clearBtn.style.display = hasSculpt() ? "block" : "none";
+  }
+  const BASE_COLORS = new Float32Array(COLORS);   // pristine per-vertex colors
+  // Vertices grouped by zone, for fast hover recolor.
+  const zoneVerts = {};
+  for (let i = 0; i < ZONES.length; i++) {
+    (zoneVerts[ZONES[i]] || (zoneVerts[ZONES[i]] = [])).push(i);
+  }
+
   // Spherical camera around TARGET. Front-facing default: on +Z axis.
   let camState = { radius: 0.75, theta: 0.0, phi: Math.PI / 2 };
 
@@ -354,29 +627,113 @@ VIEWER_JS_ON_LOAD = """
     camera.lookAt(tx, ty, tz);
   }
 
-  function setPositions(flat) {
-    if (!geometry) return;
+  // Write lastFlat (+ any sculpt offsets) into the position buffer.
+  function applyBuffer() {
+    if (!geometry || !lastFlat) return;
+    const n = lastFlat.length;
     let attr = geometry.getAttribute("position");
-    if (!attr || attr.array.length !== flat.length) {
-      attr = new THREE.BufferAttribute(new Float32Array(flat.length), 3);
+    if (!attr || attr.array.length !== n) {
+      attr = new THREE.BufferAttribute(new Float32Array(n), 3);
       geometry.setAttribute("position", attr);
     }
-    attr.array.set(flat);
+    const a = attr.array;
+    if (sculptOffsets && sculptOffsets.length === n) {
+      for (let i = 0; i < n; i++) a[i] = lastFlat[i] + sculptOffsets[i];
+    } else {
+      a.set(lastFlat);
+    }
     attr.needsUpdate = true;
     geometry.computeVertexNormals();
     geometry.computeBoundingSphere();
+    geometry.computeBoundingBox();
+  }
+
+  function setPositions(flat) {
+    lastFlat = flat;
+    if (!sculptOffsets && flat.length) sculptOffsets = new Float32Array(flat.length);
+    applyBuffer();
+  }
+
+  // ---- Slider registry access (set by each vertical slider on mount). -----
+  function reg(k) {
+    return (window.__GNM && window.__GNM.reg) ? window.__GNM.reg[k] : null;
+  }
+  function getV(k) { const r = reg(k); return r ? parseFloat(r.get()) : 0; }
+  function setV(k, v) { const r = reg(k); if (r) r.set(v); }
+
+  // ---- Always-on region colour map + hover highlight ----------------------
+  // Every mapped zone is permanently tinted toward its HL colour at FAINT
+  // strength (the "control map"); the hovered zone is boosted to BRIGHT.
+  const FAINT = 0.32, BRIGHT = 0.78;
+  let hlZone = -1;
+
+  // Tint a zone's vertices toward its map colour by `strength` (0 = base).
+  function tintZone(z, strength) {
+    const vs = zoneVerts[z], c = HL[z]; if (!vs || !c) return;
+    const a = colorAttr.array, s = strength, b = 1 - strength;
+    for (let n = 0; n < vs.length; n++) {
+      const i = vs[n] * 3;
+      a[i]   = b * BASE_COLORS[i]   + s * c[0];
+      a[i+1] = b * BASE_COLORS[i+1] + s * c[1];
+      a[i+2] = b * BASE_COLORS[i+2] + s * c[2];
+    }
+    colorAttr.needsUpdate = true;
+  }
+
+  // Paint the whole control map at FAINT strength (call once the colour
+  // attribute exists).
+  function initColorMap() {
+    for (const zk in HL) tintZone(Number(zk), FAINT);
+  }
+
+  function setHighlight(z) {
+    if (z === hlZone) return;
+    if (hlZone >= 0 && HL[hlZone]) tintZone(hlZone, FAINT);   // back to map
+    hlZone = (z >= 0 && HL[z]) ? z : -1;
+    if (hlZone >= 0) tintZone(hlZone, BRIGHT);
+  }
+
+  // ---- Slider glow: light up the control(s) a hovered region drives -------
+  const TAB_OF = { id: 0, ex: 1, pose: 2, tr: 3 };
+  let glowing = [];
+  function clearGlow() {
+    for (const el of glowing) el.classList.remove("gnm-ctl-glow");
+    glowing = [];
+  }
+  function glowZone(z) {
+    clearGlow();
+    const sp = zoneSpec(z);
+    const tabBtns = document.querySelectorAll('button[role="tab"]');
+    const seenTabs = {};
+    for (const t of (sp.t || [])) {
+      const r = reg(t.key);
+      if (r && r.el) { r.el.classList.add("gnm-ctl-glow"); glowing.push(r.el); }
+      const ti = TAB_OF[String(t.key).split("_")[0]];
+      if (ti != null && tabBtns[ti] && !seenTabs[ti]) {
+        seenTabs[ti] = 1;
+        tabBtns[ti].classList.add("gnm-ctl-glow"); glowing.push(tabBtns[ti]);
+      }
+    }
   }
 
   function build() {
     const wrap = element.querySelector("#gnm-wrap");
     const canvas = element.querySelector("#gnm-canvas");
+    const hint = element.querySelector("#gnm-hint");
+    clearBtn = element.querySelector("#gnm-clear-sculpt");
+    if (clearBtn) {
+      clearBtn.addEventListener("click", () => {
+        if (sculptOffsets) sculptOffsets.fill(0);
+        applyBuffer();
+        updateClearBtn();
+      });
+    }
     if (!wrap || !canvas || !window.THREE) return false;
     const W = wrap.clientWidth || 600, H = wrap.clientHeight || 560;
 
     renderer = new THREE.WebGLRenderer({ canvas: canvas, antialias: true });
     renderer.setPixelRatio(window.devicePixelRatio || 1);
     renderer.setSize(W, H, false);
-    // Tone down exposure so the mesh isn't blown out / overexposed.
     renderer.toneMapping = THREE.ACESFilmicToneMapping;
     renderer.toneMappingExposure = 0.85;
 
@@ -386,18 +743,17 @@ VIEWER_JS_ON_LOAD = """
     camera = new THREE.PerspectiveCamera(35, W / H, 0.01, 100);
     applyCamera();
 
-    // Reduced light intensities so the mesh isn't overexposed / blown out.
     scene.add(new THREE.AmbientLight(0xffffff, 0.40));
-    const key = new THREE.DirectionalLight(0xffffff, 0.55);
-    key.position.set(0.5, 1.0, 1.5); scene.add(key);
+    const keyL = new THREE.DirectionalLight(0xffffff, 0.55);
+    keyL.position.set(0.5, 1.0, 1.5); scene.add(keyL);
     const fill = new THREE.DirectionalLight(0xffffff, 0.20);
     fill.position.set(-0.8, 0.2, 0.5); scene.add(fill);
 
     geometry = new THREE.BufferGeometry();
     geometry.setIndex(new THREE.BufferAttribute(new Uint32Array(FACES), 1));
-    geometry.setAttribute(
-      "color", new THREE.BufferAttribute(new Float32Array(COLORS), 3)
-    );
+    colorAttr = new THREE.BufferAttribute(new Float32Array(COLORS), 3);
+    geometry.setAttribute("color", colorAttr);
+    initColorMap();   // paint the always-on region map
     const mat = new THREE.MeshStandardMaterial({
       vertexColors: true, roughness: 0.75, metalness: 0.0,
       side: THREE.DoubleSide,
@@ -405,21 +761,208 @@ VIEWER_JS_ON_LOAD = """
     mesh = new THREE.Mesh(geometry, mat);
     scene.add(mesh);
 
-    // --- Minimal orbit controls (rotate/zoom); never auto-resets. ---------
-    let dragging = false, lastX = 0, lastY = 0;
-    canvas.addEventListener("mousedown", (e) => {
-      dragging = true; lastX = e.clientX; lastY = e.clientY;
+    // ---- Raycasting: screen point -> mesh hit -> interaction zone. --------
+    const raycaster = new THREE.Raycaster();
+    const ndc = new THREE.Vector2();
+    function pick(clientX, clientY) {
+      const rect = canvas.getBoundingClientRect();
+      ndc.x = ((clientX - rect.left) / rect.width) * 2 - 1;
+      ndc.y = -((clientY - rect.top) / rect.height) * 2 + 1;
+      raycaster.setFromCamera(ndc, camera);
+      const hits = raycaster.intersectObject(mesh, false);
+      if (!hits.length) return null;
+      const f = hits[0].face;
+      // Prefer a feature zone if any of the face's 3 verts carries one.
+      let z = ZONES[f.a];
+      if (z === Z_HEAD && ZONES[f.b] !== Z_HEAD) z = ZONES[f.b];
+      if (z === Z_HEAD && ZONES[f.c] !== Z_HEAD) z = ZONES[f.c];
+      // Nearest of the face's 3 vertices to the hit point (for sculpting).
+      const P = hits[0].point, pos = geometry.getAttribute("position");
+      let vi = f.a, best = Infinity;
+      for (const vv of [f.a, f.b, f.c]) {
+        const dx = pos.getX(vv) - P.x, dy = pos.getY(vv) - P.y,
+              dz = pos.getZ(vv) - P.z, dd = dx * dx + dy * dy + dz * dz;
+        if (dd < best) { best = dd; vi = vv; }
+      }
+      return { zone: z, point: P, vi: vi };
+    }
+
+    function showHint(text) {
+      if (!hint) return;
+      hint.textContent = text || "";
+      hint.style.opacity = text ? "1" : "0";
+    }
+
+    // ---- Interaction state machine ----------------------------------------
+    // mode: null | 'orbit' | 'manip' | 'trans' | 'sculpt'
+    let mode = null, spec = null, startX = 0, startY = 0, startVals = null;
+    let orbitLastX = 0, orbitLastY = 0, pendingApply = null;
+    let brush = null;   // { list:[{i,w}], base: Float32Array } for a sculpt drag
+
+    // Meters of world space per screen pixel at the head, for the current
+    // camera — turns a sculpt drag (pixels) into a world displacement so the
+    // grabbed point tracks the cursor.
+    function metersPerPixel() {
+      const h = canvas.clientHeight || 560;
+      const fov = (camera.fov || 35) * Math.PI / 180;
+      return (2 * camState.radius * Math.tan(fov / 2)) / h;
+    }
+
+    // Sculpt brush: free-form pull of the surface under the cursor. All
+    // vertices within SCULPT_R of the grabbed point move with the drag,
+    // weighted by a smooth falloff, so pulling a cheek stretches the face and
+    // pulling an ear pushes it in/out. Offsets persist across mesh morphs.
+    const SCULPT_R = 0.05;   // brush radius (meters)
+
+    function beginSculpt(hit, e) {
+      const pos = geometry.getAttribute("position");
+      const gx = pos.getX(hit.vi), gy = pos.getY(hit.vi), gz = pos.getZ(hit.vi);
+      const list = [];
+      for (let v = 0; v < ZONES.length; v++) {
+        const dx = pos.getX(v) - gx, dy = pos.getY(v) - gy, dz = pos.getZ(v) - gz;
+        const dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
+        if (dist < SCULPT_R) {
+          const t = 1 - dist / SCULPT_R;
+          list.push({ i: v, w: t * t * (3 - 2 * t) });   // smoothstep falloff
+        }
+      }
+      // Snapshot the current offsets so the drag is absolute (drag back undoes).
+      const base = new Float32Array(list.length * 3);
+      for (let n = 0; n < list.length; n++) {
+        const j = list[n].i * 3;
+        base[n * 3] = sculptOffsets[j];
+        base[n * 3 + 1] = sculptOffsets[j + 1];
+        base[n * 3 + 2] = sculptOffsets[j + 2];
+      }
+      brush = { list, base };
+      startX = e.clientX; startY = e.clientY;
+      mode = 'sculpt';
+      // Keep the zone highlight lit while sculpting a feature (ear/cheek); use
+      // its label if it has one, else a generic sculpt hint.
+      const sp = zoneSpec(hit.zone);
+      if (SCULPT_ZONES[hit.zone]) setHighlight(hit.zone); else setHighlight(-1);
+      showHint(sp.label || "🫳  Sculpt · drag to stretch / pull the surface");
+    }
+
+    function beginManip(z, hit, e) {
+      const base = zoneSpec(z);
+      // Resolve any `outwardX` target to a concrete sign from the grab point:
+      // grabbing the +x side and dragging +x (or -x side dragging -x) both
+      // count as pulling "outward". World +x maps to screen-right in the
+      // front view, so screen dx and world x share a direction here.
+      const gx = (hit && hit.point) ? hit.point.x : 0;
+      spec = {
+        label: base.label,
+        t: base.t.map((t) => {
+          if (t.outwardX)    return { ...t, sign: (gx >= 0 ? -1 : 1) };  // outward -> negative
+          if (t.outwardXPos) return { ...t, sign: (gx >= 0 ? 1 : -1) };  // outward -> positive
+          return t;
+        }),
+      };
+      startX = e.clientX; startY = e.clientY; startVals = {};
+      for (const t of spec.t) startVals[t.key] = getV(t.key);
+      mode = 'manip';
+      setHighlight(z);
+      glowZone(z);
+      showHint(spec.label);
+    }
+
+    canvas.addEventListener("contextmenu", (e) => e.preventDefault());
+
+    canvas.addEventListener("pointerdown", (e) => {
+      try { canvas.setPointerCapture(e.pointerId); } catch (err) {}
+      const rightBtn = (e.button === 2);
+      if (e.shiftKey && !rightBtn) {                 // Shift+drag = translate
+        mode = 'trans';
+        spec = { t: [ {key: CFG.txKey, axis:'x', gain: TRANS_G, sign: +1},
+                      {key: CFG.tyKey, axis:'y', gain: TRANS_G, sign: +1} ] };
+        startX = e.clientX; startY = e.clientY; startVals = {};
+        for (const t of spec.t) startVals[t.key] = getV(t.key);
+        showHint("✚  Move head · drag to reposition");
+        e.preventDefault(); return;
+      }
+      const hit = rightBtn ? null : pick(e.clientX, e.clientY);
+      if (hit && (e.altKey || e.metaKey || SCULPT_ZONES[hit.zone])) {
+        beginSculpt(hit, e);                         // ear/cheek, or Alt+drag
+      } else if (hit) {                              // grab the head itself
+        beginManip(hit.zone, hit, e);
+      } else {                                        // empty space / RMB = orbit
+        mode = 'orbit'; orbitLastX = e.clientX; orbitLastY = e.clientY;
+      }
+      e.preventDefault();
     });
-    window.addEventListener("mouseup", () => { dragging = false; });
-    window.addEventListener("mousemove", (e) => {
-      if (!dragging) return;
-      const dx = e.clientX - lastX, dy = e.clientY - lastY;
-      lastX = e.clientX; lastY = e.clientY;
-      camState.theta -= dx * 0.01;
-      camState.phi = Math.max(0.05, Math.min(Math.PI - 0.05,
-                       camState.phi - dy * 0.01));
-      applyCamera();
+
+    window.addEventListener("pointermove", (e) => {
+      if (mode === 'orbit') {
+        const dx = e.clientX - orbitLastX, dy = e.clientY - orbitLastY;
+        orbitLastX = e.clientX; orbitLastY = e.clientY;
+        camState.theta -= dx * 0.01;
+        camState.phi = Math.max(0.05, Math.min(Math.PI - 0.05,
+                         camState.phi - dy * 0.01));
+        applyCamera();
+        return;
+      }
+      if (mode === 'manip' || mode === 'trans') {
+        const dx = e.clientX - startX, dy = e.clientY - startY;
+        // Coalesce to one apply per animation frame (caps server round-trips).
+        pendingApply = () => {
+          for (const t of spec.t) {
+            const raw = (t.axis === 'x') ? dx : -dy;
+            setV(t.key, startVals[t.key] + raw * t.gain * t.sign);
+          }
+        };
+        e.preventDefault();
+        return;
+      }
+      if (mode === 'sculpt') {
+        const dx = e.clientX - startX, dy = e.clientY - startY;
+        pendingApply = () => {
+          if (!brush || !sculptOffsets) return;
+          // Screen drag -> world pull in the camera plane (right = +x screen,
+          // up = -y screen), so the grabbed point follows the cursor.
+          camera.updateMatrixWorld();
+          const m = camera.matrixWorld.elements;
+          const k = metersPerPixel() * SCULPT_G;
+          const wx = (m[0] * dx - m[4] * dy) * k;
+          const wy = (m[1] * dx - m[5] * dy) * k;
+          const wz = (m[2] * dx - m[6] * dy) * k;
+          const list = brush.list, base = brush.base;
+          for (let n = 0; n < list.length; n++) {
+            const j = list[n].i * 3, w = list[n].w;
+            sculptOffsets[j]     = base[n * 3]     + w * wx;
+            sculptOffsets[j + 1] = base[n * 3 + 1] + w * wy;
+            sculptOffsets[j + 2] = base[n * 3 + 2] + w * wz;
+          }
+          applyBuffer();
+          updateClearBtn();
+        };
+        e.preventDefault();
+        return;
+      }
+      // Hovering (no button held): brighten the zone under the cursor and
+      // glow the control(s) it drives.
+      if (e.buttons === 0) {
+        const hit = pick(e.clientX, e.clientY);
+        if (hit) {
+          showHint(zoneSpec(hit.zone).label);
+          setHighlight(hit.zone);
+          glowZone(hit.zone);
+          canvas.style.cursor = "grab";
+        } else {
+          showHint(""); setHighlight(-1); clearGlow();
+          canvas.style.cursor = "default";
+        }
+      }
     });
+
+    function endDrag() {
+      if (pendingApply) { pendingApply(); pendingApply = null; }
+      mode = null; spec = null; startVals = null; brush = null;
+      setHighlight(-1); showHint(""); clearGlow();
+    }
+    window.addEventListener("pointerup", endDrag);
+    window.addEventListener("pointercancel", endDrag);
+
     canvas.addEventListener("wheel", (e) => {
       e.preventDefault();
       camState.radius = Math.max(0.2, Math.min(3.0,
@@ -427,8 +970,22 @@ VIEWER_JS_ON_LOAD = """
       applyCamera();
     }, { passive: false });
 
+    // Slider-driving drags round-trip to the server per update; firing every
+    // frame backs up the queue and the mesh lags behind the cursor. Throttle
+    // them to send only the *latest* value at a sustainable rate (no backlog =
+    // real-time feel). Client-side sculpt has no round-trip, so it stays at
+    // full framerate.
+    let lastSlideT = 0;
+    const SLIDE_MS = 40;
     function animate() {
       requestAnimationFrame(animate);
+      if (pendingApply) {
+        const throttled = (mode === 'manip' || mode === 'trans');
+        if (!throttled || (performance.now() - lastSlideT) >= SLIDE_MS) {
+          pendingApply(); pendingApply = null;
+          if (throttled) lastSlideT = performance.now();
+        }
+      }
       renderer.render(scene, camera);
     }
     animate();
@@ -450,8 +1007,6 @@ VIEWER_JS_ON_LOAD = """
     if (flat && flat.length) setPositions(flat);
   }
 
-  // Wait for the global THREE (head script) then build once, then draw the
-  // initial value. watch() handles every subsequent update in place.
   (function ready() {
     if (!window.THREE || !build()) { setTimeout(ready, 40); return; }
     updateFromValue();
@@ -464,9 +1019,40 @@ VIEWER_JS_ON_LOAD = (
     VIEWER_JS_ON_LOAD
     .replace("__FACES__", _FACES_JSON)
     .replace("__COLORS__", _COLORS_JSON)
+    .replace("__ZONES__", ZONES_JSON)
+    .replace("__CFG__", VIEWER_CFG_JSON)
+    .replace("__NUM_IDENTITY__", str(NUM_IDENTITY))
 )
 
 
+# Hidden "sculpt bus": a zero-size custom component whose value carries the
+# free-pull payload. The viewer writes to it via window.__GNM.sculptSet during
+# an Alt-drag, which fires its .change() -> sculpt_pull -> identity sliders.
+SCULPT_BUS_JS = """
+(function () {
+  window.__GNM = window.__GNM || {};
+  window.__GNM.sculptSet = function (v) { props.value = v; };
+
+  // Gradio only mounts the *active* tab's contents, so sliders in the other
+  // tabs never register on the __GNM bus and the 3D head can't drive them.
+  // Mount every tab once (click through them), then return to the first — the
+  // rendered panels stay in the DOM (hidden), so all sliders stay registered.
+  (function mountTabs(tries) {
+    const tabs = Array.from(document.querySelectorAll('button[role="tab"]'));
+    if (tabs.length < 2) {
+      if ((tries || 0) < 60) setTimeout(function () { mountTabs((tries || 0) + 1); }, 100);
+      return;
+    }
+    let i = 0;
+    (function step() {
+      if (i < tabs.length) { tabs[i].click(); i++; setTimeout(step, 120); }
+      else { tabs[0].click(); }
+    })();
+  })();
+})();
+"""
+
+
 # ---------------------------------------------------------------------------
 # UI
 # ---------------------------------------------------------------------------
@@ -474,6 +1060,31 @@ CSS = """
 #col-container { max-width: 1200px; margin: 0 auto; }
 .dark .gradio-container { color: var(--body-text-color); }
 
+/* Glow applied (from the 3D viewer) to the slider(s) / tab a hovered head
+   region drives, so the region <-> control correspondence is visible. */
+.gnm-ctl-glow {
+  outline: 2px solid var(--color-accent, #ff7c00) !important;
+  outline-offset: 1px;
+  border-radius: 6px;
+  box-shadow: 0 0 10px 1px var(--color-accent, #ff7c00);
+  transition: box-shadow .1s, outline-color .1s;
+}
+
+/* All slider groups are always expanded (they must stay mounted so the 3D
+   viewer can drive every one of them). To keep the page short and the head
+   always visible beside them, the controls column scrolls *internally* and
+   the viewer stays pinned next to it. */
+#gnm-main-row { align-items: flex-start !important; }
+#gnm-controls-col {
+  max-height: calc(100vh - 24px);
+  overflow-y: auto;
+  padding-right: 6px;
+}
+#gnm-viewer-col {
+  position: sticky;
+  top: 8px;
+}
+
 /* Compact grouped sections. Each feature/parameter group (Head Shape, Left
    Eye, Mouth, Neck, Gaze, Translation, ...) is rendered as its own bordered
    section with a header row (group label + per-group Reset) and its sliders
@@ -664,9 +1275,9 @@ CSS = """
 """
 
 INTRO = """
-# 🧬 GNM — Generative aNthropometric Model (Head)
+# 🧬 GNM — Direct-Manipulation Head
 
-**GNM Head** is a state-of-the-art parametric 3D statistical model of the human head from [google/GNM](https://github.com/google/GNM), with disentangled control over **identity**, **expression**, **pose** and **translation**. Move any slider to see it re-generate the 3D mesh live. Based on the [notebook demo](https://github.com/google/GNM/blob/main/gnm/shape/README.md#demo).
+**GNM Head** is a state-of-the-art parametric 3D statistical model of the human head from [google/GNM](https://github.com/google/GNM), with disentangled control over **identity**, **expression**, **pose** and **translation**. Move the sliders, or **grab the 3D head directly** — hover any part to see what it does. Based on the [notebook demo](https://github.com/google/GNM/blob/main/gnm/shape/README.md#demo).
 """
 
 
@@ -702,6 +1313,7 @@ VSLIDER_TEMPLATE = (
 VSLIDER_JS_ON_LOAD = """
 (function () {
   const MIN = __MIN__, MAX = __MAX__, STEP = __STEP__;
+  const KEY = "__KEY__";
   const root   = element.querySelector(".vslider-root");
   const track  = element.querySelector(".vslider-track");
   const fill   = element.querySelector(".vslider-fill");
@@ -788,6 +1400,36 @@ VSLIDER_JS_ON_LOAD = """
     if (!track.clientHeight) { setTimeout(ready, 30); return; }
     paint(currentValue());
   })();
+
+  // Repaint when the track gains size — e.g. when this slider's tab becomes
+  // visible after having been driven while hidden (its handle would otherwise
+  // be stuck at the wrong position). Guarded so a zero-size (hidden) pass is
+  // ignored.
+  if (window.ResizeObserver) {
+    new ResizeObserver(() => {
+      if (track.clientHeight) paint(currentValue());
+    }).observe(track);
+  }
+
+  // Expose this slider on a global registry so the 3D viewer can drive it
+  // when the user drags directly on the head. `set(v)` snaps/paints the value
+  // and writes props.value, which fires the same .change() a manual drag does
+  // (so the mesh recomputes through the exact same reactive path).
+  if (KEY) {
+    window.__GNM = window.__GNM || {};
+    window.__GNM.reg = window.__GNM.reg || {};
+    window.__GNM.reg[KEY] = {
+      set(v) {
+        const nv = clampSnap(v);
+        paint(nv);
+        if (nv !== parseFloat(props.value)) props.value = nv;
+        return nv;
+      },
+      get() { return currentValue(); },
+      min: MIN, max: MAX, step: STEP,
+      el: root,   // so the viewer can glow this slider when its region is hovered
+    };
+  }
 })();
 """
 
@@ -797,11 +1439,14 @@ def _js_num(x):
     return repr(float(x))
 
 
-def _vslider(label, minimum, maximum, value=0.0, step=None):
+def _vslider(label, minimum, maximum, value=0.0, step=None, key=None):
     """Create a custom vertical slider (drop-in replacement for gr.Slider).
 
     Returns a gr.HTML component whose value is the numeric slider value. The
     per-instance label / min / max / step are baked into its template and JS.
+    If `key` is given, the slider registers itself under that key in the
+    global `window.__GNM.reg` so the 3D viewer can drive it via direct
+    manipulation on the head.
     """
     step_val = step if step is not None else 0.0
     tmpl = (
@@ -815,6 +1460,7 @@ def _vslider(label, minimum, maximum, value=0.0, step=None):
         .replace("__MIN__", _js_num(minimum))
         .replace("__MAX__", _js_num(maximum))
         .replace("__STEP__", _js_num(step_val))
+        .replace("__KEY__", str(key) if key is not None else "")
     )
     return gr.HTML(
         value=float(value),
@@ -866,9 +1512,9 @@ with gr.Blocks(title="GNM Head") as demo:
     with gr.Column(elem_id="col-container"):
         gr.Markdown(INTRO)
 
-        with gr.Row():
+        with gr.Row(elem_id="gnm-main-row"):
             # --- Controls -------------------------------------------------
-            with gr.Column(scale=3):
+            with gr.Column(scale=3, elem_id="gnm-controls-col"):
                 identity_sliders = []
                 expression_sliders = []
                 pose_sliders = []
@@ -888,6 +1534,7 @@ with gr.Blocks(title="GNM Head") as demo:
                                     _slider(
                                         f"Head shape {k + 1}",
                                         -3.0, 3.0, 0.0, 0.05,
+                                        key=f"id_{k}",
                                     )
                                 )
                             return sliders
@@ -951,6 +1598,8 @@ with gr.Blocks(title="GNM Head") as demo:
                                     )
 
                         def _make_expr_builder(group_name, group_idx):
+                            start = _EXPR_SLOT_START[group_name]
+
                             def _build_expr():
                                 sliders = []
                                 for j in range(len(group_idx)):
@@ -962,7 +1611,10 @@ with gr.Blocks(title="GNM Head") as demo:
                                         else f"{group_name} {j + 1}"
                                     )
                                     sliders.append(
-                                        _slider(label, -3.0, 3.0, 0.0, 0.05)
+                                        _slider(
+                                            label, -3.0, 3.0, 0.0, 0.05,
+                                            key=f"ex_{start + j}",
+                                        )
                                     )
                                 return sliders
                             return _build_expr
@@ -1018,12 +1670,17 @@ with gr.Blocks(title="GNM Head") as demo:
                             "vergence control)."
                         )
 
-                        def _make_pose_builder(limits):
+                        def _make_pose_builder(limits, start):
                             def _build_pose():
                                 sliders = []
-                                for name, limit in limits.items():
+                                for i, (name, limit) in enumerate(
+                                    limits.items()
+                                ):
                                     sliders.append(
-                                        _slider(name, -limit, limit, 0, 1)
+                                        _slider(
+                                            name, -limit, limit, 0, 1,
+                                            key=f"pose_{start + i}",
+                                        )
                                     )
                                 return sliders
                             return _build_pose
@@ -1038,7 +1695,9 @@ with gr.Blocks(title="GNM Head") as demo:
                                 with gr.Column(min_width=0):
                                     pose_sliders += _group_section(
                                         joint.capitalize(),
-                                        _make_pose_builder(limits),
+                                        _make_pose_builder(
+                                            limits, _POSE_SLOT_START[joint]
+                                        ),
                                     )
 
                         for joint, limits in POSE_LIMITS.items():
@@ -1046,7 +1705,9 @@ with gr.Blocks(title="GNM Head") as demo:
                                 continue
                             pose_sliders += _group_section(
                                 joint.capitalize(),
-                                _make_pose_builder(limits),
+                                _make_pose_builder(
+                                    limits, _POSE_SLOT_START[joint]
+                                ),
                             )
 
                     with gr.Tab("Translation"):
@@ -1054,13 +1715,16 @@ with gr.Blocks(title="GNM Head") as demo:
 
                         def _build_translation():
                             sliders = []
-                            for d in [
+                            for i, d in enumerate([
                                 "X (left/right)",
                                 "Y (up/down)",
                                 "Z (forward/back)",
-                            ]:
+                            ]):
                                 sliders.append(
-                                    _slider(d, -0.2, 0.2, 0.0, 0.01)
+                                    _slider(
+                                        d, -0.2, 0.2, 0.0, 0.01,
+                                        key=f"tr_{i}",
+                                    )
                                 )
                             return sliders
 
@@ -1072,7 +1736,7 @@ with gr.Blocks(title="GNM Head") as demo:
             # The custom Three.js viewer IS the output component. Its value is
             # the flat vertex-position array; `watch('value')` in the viewer's
             # js_on_load morphs the persistent mesh in place on every update.
-            with gr.Column(scale=2):
+            with gr.Column(scale=2, elem_id="gnm-viewer-col"):
                 viewer = gr.HTML(
                     value="",
                     html_template=VIEWER_TEMPLATE,
@@ -1081,6 +1745,14 @@ with gr.Blocks(title="GNM Head") as demo:
                     label="GNM head mesh",
                     elem_id="gnm-viewer",
                 )
+                # Hidden channel for the Alt-drag sculpt payload.
+                sculpt_bus = gr.HTML(
+                    value="",
+                    html_template='<div style="display:none"></div>',
+                    js_on_load=SCULPT_BUS_JS,
+                    container=False,
+                    elem_id="gnm-sculpt-bus",
+                )
 
         all_sliders = (
             identity_sliders
@@ -1100,8 +1772,23 @@ with gr.Blocks(title="GNM Head") as demo:
                 inputs=all_sliders,
                 outputs=viewer,
                 show_progress="hidden",
+                queue=False,   # run off the queue -> lower latency for live drags
             )
 
+        # Sculpt (Alt-drag): the viewer writes a free-pull payload into the
+        # hidden sculpt bus; here we solve the identity sliders that move the
+        # grabbed vertex toward the drag, set them (which repaints the Head
+        # Shape sliders), then re-render the mesh.
+        sculpt_bus.change(
+            fn=sculpt_pull,
+            inputs=[sculpt_bus] + all_sliders,
+            outputs=identity_sliders,
+            show_progress="hidden",
+        ).then(
+            fn=positions_json, inputs=all_sliders, outputs=viewer,
+            show_progress="hidden",
+        )
+
         # Per-group Reset: each group has its own ↺ Reset button that resets
         # ONLY that group's sliders back to their defaults, then recomputes the
         # mesh from the full (partially-reset) slider vector. There is no