Tour: draggable callout with a grab handle (tap to flip up/down)

The tour callout was a fixed banner that could still cover controls on mobile.
It now has a grab handle at the top:
- DRAG it anywhere (clamped to the viewport).
- TAP it (no real movement) to flip between two snap presets — DOWN (above the
on-screen controls) and UP (just below the top UI).
The chosen position persists across steps and is saved, so it stays put as the
tour advances. Pointer events cover touch + mouse; a 5px dead zone keeps a tap
from registering as a drag.

Replaces the per-anchor REGION map (every step mapped to one banner anyway) with
the two presets + free placement.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

web/tutorial.js

@@ -19,18 +19,16 @@ function elc(tag, css, text) { const n = document.createElement(tag); if (css) n
   } catch { /* ignore */ }
 })()
 
-// Place a fixed-position callout in a screen region, offset so it doesn't cover the control.
-// All anchors sit in the LOWER part of the screen so the callout never covers the map, the create
-// modal, the picker or the top UI — and you can still read + click through. 'bottom' is the default
-// banner (centred, just above the on-screen controls); the others nudge left/right toward a control.
-// One consistent banner low on the screen (centred, above the on-screen controls + picker) so the
-// callout never covers the map, the create modal, the picker or the top UI — you can read it and
-// still click through everywhere else. Every step maps here.
-const BANNER = 'left:50%;bottom:170px;transform:translateX(-50%)'
-const REGION = { center: BANNER, bottom: BANNER, 'bottom-center': BANNER, 'bottom-left': BANNER, 'bottom-right': BANNER, 'top-left': BANNER, 'top-right': BANNER, right: BANNER }
+// The callout is a single draggable banner. Two snap presets keep it out of the way: DOWN (above the
+// on-screen controls) and UP (just below the top UI). The handle lets you drag it anywhere, or tap to
+// flip between the presets — so on mobile it never has to block whatever you need to reach.
+const PRESETS = {
+  down: { left: '50%', bottom: '150px', transform: 'translateX(-50%)' },
+  up: { left: '50%', top: '64px', transform: 'translateX(-50%)' },
+}
 
 export function createTutorial(steps) {
-  let state = { step: 0, done: false, dismissed: false, ...load() }
+  let state = { step: 0, done: false, dismissed: false, placement: { mode: 'preset', preset: 'down' }, ...load() }
   let idx = -1, box = null
   let glowEl = null, glowTimer = null
   const persist = () => save(state)
@@ -54,6 +52,63 @@ export function createTutorial(steps) {
     tick(); glowTimer = setInterval(tick, 400)
   }
 
+  // Position the callout from state.placement: a free x/y (after dragging) or one of the snap presets.
+  function applyPlacement(b) {
+    if (!b) return
+    b.style.left = b.style.top = b.style.bottom = b.style.right = b.style.transform = ''
+    const pl = state.placement || (state.placement = { mode: 'preset', preset: 'down' })
+    if (pl.mode === 'free' && pl.left != null) {
+      b.style.left = pl.left + 'px'; b.style.top = pl.top + 'px'
+    } else {
+      const p = PRESETS[pl.preset] || PRESETS.down
+      for (const k in p) b.style[k] = p[k]
+    }
+  }
+
+  // A grab handle at the top of the callout: DRAG to place it anywhere (clamped to the viewport), or
+  // TAP (no real movement) to flip between the up/down snap presets. Pointer events cover touch + mouse.
+  function buildHandle() {
+    const h = elc('div', 'cursor:grab;touch-action:none;user-select:none;-webkit-user-select:none;-webkit-touch-callout:none;margin:-13px -15px 10px;padding:9px 15px 8px;border-bottom:1px solid #2a2a17;display:flex;align-items:center;justify-content:center;gap:8px')
+    const grip = elc('div', 'display:flex;gap:3px;align-items:center')
+    for (let i = 0; i < 3; i++) grip.appendChild(elc('span', 'width:4px;height:4px;border-radius:50%;background:#7a8294'))
+    h.append(grip, elc('span', 'font-size:10px;color:#6b7686', 'drag to move · tap to flip'))
+    let start = null, moved = false
+    const onDown = (e) => {
+      const r = box.getBoundingClientRect()
+      start = { px: e.clientX, py: e.clientY, bx: r.left, by: r.top }
+      moved = false; h.style.cursor = 'grabbing'
+      try { h.setPointerCapture(e.pointerId) } catch { /* ignore */ }
+      e.preventDefault()
+    }
+    const onMove = (e) => {
+      if (!start) return
+      const dx = e.clientX - start.px, dy = e.clientY - start.py
+      if (!moved && Math.hypot(dx, dy) > 5) moved = true // small dead zone so a tap isn't read as a drag
+      if (!moved) return
+      const w = box.offsetWidth, ht = box.offsetHeight
+      const nx = Math.max(6, Math.min(window.innerWidth - w - 6, start.bx + dx))
+      const ny = Math.max(6, Math.min(window.innerHeight - ht - 6, start.by + dy))
+      state.placement = { mode: 'free', preset: (state.placement && state.placement.preset) || 'down', left: nx, top: ny }
+      applyPlacement(box)
+    }
+    const onUp = (e) => {
+      if (!start) return
+      start = null; h.style.cursor = 'grab'
+      try { h.releasePointerCapture(e.pointerId) } catch { /* ignore */ }
+      if (!moved) { // a tap → flip to the other snap preset
+        const cur = state.placement && state.placement.preset === 'up' ? 'up' : 'down'
+        state.placement = { mode: 'preset', preset: cur === 'down' ? 'up' : 'down' }
+        applyPlacement(box)
+      }
+      persist()
+    }
+    h.addEventListener('pointerdown', onDown)
+    h.addEventListener('pointermove', onMove)
+    h.addEventListener('pointerup', onUp)
+    h.addEventListener('pointercancel', onUp)
+    return h
+  }
+
   const shouldAutoStart = () => !state.done && !state.dismissed
   function startOrResume() { if (state.done) return; idx = Math.min(state.step || 0, steps.length - 1); show() }
   function emit(event) { const s = steps[idx]; if (idx >= 0 && s && s.advanceOn === event) advance() }
@@ -68,7 +123,8 @@ export function createTutorial(steps) {
     if (!s) return finish()
     state.step = idx; persist()
     teardown()
-    box = elc('div', `position:fixed;z-index:40;max-width:300px;background:#11151c;border:1px solid #c9a227;border-radius:12px;padding:13px 15px;color:#e8e8e8;font:13px var(--tac-font,system-ui);box-shadow:0 8px 30px rgba(0,0,0,.55);line-height:1.45;${REGION[s.anchor] || REGION.center}`)
+    box = elc('div', 'position:fixed;z-index:40;max-width:300px;background:#11151c;border:1px solid #c9a227;border-radius:12px;padding:13px 15px;color:#e8e8e8;font:13px var(--tac-font,system-ui);box-shadow:0 8px 30px rgba(0,0,0,.55);line-height:1.45')
+    box.appendChild(buildHandle())
     const t = elc('div', 'margin-bottom:11px', typeof s.text === 'function' ? s.text() : s.text)
     box.appendChild(t)
     const row = elc('div', 'display:flex;gap:8px;justify-content:flex-end;align-items:center')
@@ -82,6 +138,7 @@ export function createTutorial(steps) {
     nx.type = 'button'; nx.addEventListener('click', advance); row.appendChild(nx)
     box.appendChild(row)
     document.body.appendChild(box)
+    applyPlacement(box) // restore the player's chosen position (snap preset or dragged spot)
     trackGlow(s.target) // pulse the control this step is pointing at (if any)
   }