Window curvature: the press contract documented once

- docs/window-curvature.md holds the full contract (now also: the next
  press starts at 1x, return values, a drag keeps its value, neither side
  restores the other's state); the patch headers of window-curvature and
  frame-controls point to it and keep only their own side.
- frame-controls header: the localStorage history points to
  docs/ui-patches.md#persistent-state.
Comments only, no VERSION bumps.

docs/window-curvature.md

@@ -70,16 +70,23 @@ Debugging: `window.__sfuiWindowCurvature.dump()` (`.log` recent events).
 ### Contract for other patches
 
 For patches handling presses on the curvature controls (e.g. the window
-control bar's long press): every element the patch drives has class
+control bar's long press); the curvature patch owns press-and-drag on them:
-`sfui-curv-ctl`; when a press becomes a drag, a bubbling `CustomEvent`
+
-`sfui-curv-dragstart` (detail `{ frameID, where: 'menu' | 'bar' }`) is
+- Every element the patch drives has class `sfui-curv-ctl`.
-dispatched on it, and `sfui-curv-dragend` when it ends;
+- When a press becomes a drag (`dragThresholdPixels` vertical from where the
-`window.__sfuiWindowCurvature.scalePressDragThreshold(factor)` sets the
+  press started), a bubbling `CustomEvent` `sfui-curv-dragstart` (detail
-current press's drag threshold to `factor` × `dragThresholdPixels` (from the
+  `{ frameID, where: 'menu' | 'bar' }`) is dispatched on the element, and
-press start; returns whether it applied, i.e. a press that is not yet a
+  `sfui-curv-dragend` when that drag ends (release or `cancelPress()`).
-drag); `window.__sfuiWindowCurvature.cancelPress()` ends a press without its
+- `window.__sfuiWindowCurvature.scalePressDragThreshold(factor)` sets the
-click. A patch with its own gesture lets `mousemove` through while
+  current press's drag threshold to `factor` × `dragThresholdPixels`, still
-undecided, drops its gesture on `sfui-curv-dragstart`, may raise the
+  measured from the press start; returns whether it applied (a press that
-threshold while its gesture is under way, and calls `cancelPress()` when it
+  is not yet a drag). The next press starts at 1×.
-takes the press over. The window control bar uses factor 3 once its
+- `window.__sfuiWindowCurvature.cancelPress()` ends the current press
-progress ring shows.
+  without its click (a drag keeps its value); returns whether a press was
+  active.
+
+A patch with its own gesture lets `mousemove` through while undecided,
+drops its gesture on `sfui-curv-dragstart`, may raise the threshold while
+its gesture is under way, and calls `cancelPress()` when it takes the press
+over. Neither side reads the other's thresholds or restores the other's
+state. The window control bar uses factor 3 once its progress ring shows.

modules/frame-controls/patch.js

@@ -28,25 +28,19 @@
 // re-patch and unpatch), saved on every change through the injector's
 // persistent store (window.__sfuiStore, patch registered with state = true:
 // ~/.local/state/steam-frame-nix/ui-patches/frame-controls.json), which
-// seeds a fresh page (SteamVR restart, reboot, reload). localStorage can't
+// seeds a fresh page (SteamVR restart, reboot, reload; localStorage doesn't
-// do that: steamvr.service deletes ~/.cache/SteamVR (vrwebhelper's profile)
+// survive SteamVR starts, see docs/ui-patches.md#persistent-state).
-// on every start (which also took version 4's localStorage copy with it).
 //
 // Long press: the dashboard only gets primary-button laser input (no right
 // click; thumbstick click arrives as nothing). Holding changes nothing; the
 // timer survives the laser leaving the control, an early release cancels it.
 // On completion the popup opens and the next click on that control is
 // swallowed so its stock action doesn't run.
-// Contract with window-curvature (whose controls own press-and-drag): its
+// With window-curvature (docs/window-curvature.md#contract-for-other-patches):
-// elements carry class sfui-curv-ctl; a drag there dispatches a bubbling
+// 'sfui-curv-dragstart' cancels the long press (a drag always wins); when the
-// CustomEvent 'sfui-curv-dragstart', which cancels the long press (a drag
+// ring shows, scalePressDragThreshold(CURV_RING_THRESHOLD) lets laser drift
-// always wins). When the ring shows, the press's drag threshold is raised to
+// keep the long press; on completion cancelPress() takes the press over (no
-// CURV_RING_THRESHOLD x its own via
+// curvature click on release).
-// window.__sfuiWindowCurvature.scalePressDragThreshold(), still measured from
-// the press start: laser drift keeps the long press, a deliberate drag still
-// cancels it. On completion the long press takes the press over via
-// cancelPress() (no curvature click on release). Neither reads the other's
-// thresholds.
 //
 // Popup: its own scene-graph panel so the bar/menu panels don't change. The
 // dashboard builds its scene graph from the DOM (vsg-transform attributes,

modules/window-curvature/patch.js

@@ -44,27 +44,12 @@
 // Sliding per step (at most every 30 ms). During a drag the dashboard's own
 // haptics (hover clicks on buttons the laser passes) are muted.
 //
-// Contract with other patches (e.g. frame-controls' long press); this patch
+// Contract with other patches (e.g. frame-controls' long press), documented
-// owns press-and-drag on its controls:
+// in docs/window-curvature.md#contract-for-other-patches: this patch owns
-//   - Every element it drives has the class `sfui-curv-ctl`.
+// press-and-drag on its controls (class sfui-curv-ctl), dispatches
-//   - When a press becomes a drag (opts.dragThresholdPixels px vertical from
+// sfui-curv-dragstart / sfui-curv-dragend, and offers
-//     where the press started) it dispatches a bubbling CustomEvent
+// scalePressDragThreshold(factor) and cancelPress() on
-//     `sfui-curv-dragstart` on the element (detail { frameID, where: 'menu' |
+// window.__sfuiWindowCurvature.
-//     'bar' }); when that drag ends (release or cancelPress),
-//     `sfui-curv-dragend`.
-//   - window.__sfuiWindowCurvature.scalePressDragThreshold(factor) sets the
-//     current press's threshold to factor x opts.dragThresholdPixels, still
-//     measured from the press start, so small laser drift doesn't start a
-//     drag while a deliberate one still does; returns whether it applied
-//     (a press that is not yet a drag). The next press starts at 1x.
-//   - window.__sfuiWindowCurvature.cancelPress() ends the current press
-//     without its click (a drag keeps its value); returns whether a press
-//     was active.
-// A patch with its own gesture on these elements lets mousemove through while
-// undecided, drops its gesture on `sfui-curv-dragstart`, may raise the
-// threshold with scalePressDragThreshold() while its gesture is under way,
-// and calls cancelPress() when it takes the press over. Neither side reads
-// the other's thresholds or restores the other's state.
 //
 // Debugging: window.__sfuiWindowCurvature: dump(), hits (rewrite/haptic
 // counters), log, setValue(frameID, v), controls(), cancelPress(),
@@ -346,7 +331,6 @@ ${ROW}:last-child > .sfui-curv-ind { margin-bottom: -14px; }
     } catch (e) { log(`${type} listener failed`, String(e)); }
   };
 
-
   const onMove = (e) => {
     const p = press;
     if (!p) return;