jsgui3-server 0.0.135 → 0.0.136

package/examples/controls/14d) window, canvas globe/ARCBALL-README.md

@@ -0,0 +1,146 @@
+# Arcball Drag Behavior - Modularized Implementation
+
+## Overview
+
+This directory contains a **working, tested implementation** of arcball drag behavior that has been modularized into reusable components. The implementation is isolated from UI concerns and thoroughly tested with pure mathematical tests.
+
+## Architecture
+
+### Core Components
+
+1. **`drag-behaviour-base.js`** - Base class for drag behaviors
+   - Handles common drag state (dragging flag, timing)
+   - Provides lifecycle hooks: `on_drag_start()`, `on_drag_move()`, `on_drag_end()`
+   - Foundation for any drag behavior, not specific to arcball
+
+2. **`arcball-drag-behaviour.js`** - Arcball-specific drag behavior
+   - Extends `DragBehaviourBase`
+   - Implements the sophisticated arcball math:
+     - `screen_to_arcball()` - Projects 2D screen coords to 3D sphere
+     - Quaternion-based rotation composition
+     - Angular velocity calculation
+     - Exponential inertia decay
+   - **This contains the core math that makes arcball rotation work correctly**
+
+3. **`drag-controller.js`** - UI event wiring
+   - Handles DOM pointer events (down, move, up, cancel)
+   - Manages pointer capture
+   - Transforms screen coordinates to normalized space
+   - Delegates to behavior instance
+   - Completely separate from the math
+
+4. **`math.js`** - Quaternion and matrix utilities
+   - Pure math functions for 3D rotations
+   - Used by arcball behavior
+   - Independently tested
+
+### Integration
+
+**`EarthGlobeRenderer.js`** uses these components:
+```javascript
+this.drag_behaviour = new ArcballDragBehaviour({...});
+this.drag_controller = new DragController(canvas, this.drag_behaviour, {...});
+```
+
+## Tests
+
+### Pure Mathematical Tests (No Browser APIs)
+
+**`math.test.js`** (21 tests) - Tests quaternion & matrix math:
+- Quaternion operations (identity, normalize, multiply, from axis-angle, from vectors)
+- Matrix operations (from quaternion, transpose)
+- Integration tests (vector rotation, composition)
+
+**`arcball-drag-behaviour.test.js`** (15 tests) - Tests arcball behavior:
+- Screen-to-arcball projection
+- Drag rotation mathematics
+- Vector length preservation
+- Quaternion normalization
+- Matrix orthogonality
+- Edge cases (zero drag, tiny movements, large movements)
+- Angular velocity and inertia decay
+
+### Running Tests
+
+```bash
+cd "examples/controls/14d) window, canvas globe"
+npx mocha "*.test.js"
+```
+
+All 36 tests pass ✓
+
+## Key Arcball Math
+
+### 1. Screen to Arcball Projection
+
+Maps 2D normalized coordinates `(x, y)` to a point on a unit sphere:
+
+- **Inside unit circle**: `z = sqrt(1 - x² - y²)` (sphere equation)
+- **Outside unit circle**: Project onto edge with `z = 0`
+- Result is always a unit vector on the sphere surface
+
+### 2. Rotation Composition
+
+When dragging from point `v0` to `v1` on the arcball:
+
+1. Compute quaternion `dq` that rotates `v0` to `v1`
+2. Compose with existing rotation: `q = dq * q`
+3. Normalize to maintain unit quaternion
+4. Update rotation matrices from quaternion
+
+### 3. Inertia
+
+- Calculate angular velocity `ω` from drag movement
+- Extract rotation axis from quaternion
+- Apply exponential decay: `ω(t) = ω₀ * e^(-friction * t)`
+
+## Integration into Other Projects
+
+To use this arcball implementation in another project:
+
+### Option 1: Copy the Behavior Classes
+
+Copy these files:
+- `drag-behaviour-base.js`
+- `arcball-drag-behaviour.js`
+- `math.js`
+
+Then wire up UI events yourself, or adapt `drag-controller.js`.
+
+### Option 2: Use as Reference
+
+The **tests** (`*.test.js`) define the expected behavior mathematically. You can:
+1. Copy the test files
+2. Run them against your own implementation
+3. Fix any failures to match the correct behavior
+
+### Validation
+
+The tests verify:
+- ✓ Proper sphere projection for all input coordinates
+- ✓ Unit quaternions maintained through all operations
+- ✓ Orthogonal rotation matrices
+- ✓ Vector lengths preserved after rotation
+- ✓ Correct rotation axes for horizontal/vertical drags
+- ✓ Stability with edge cases (zero movement, tiny movements, huge movements)
+- ✓ No NaN values under any conditions
+
+## Notes
+
+- All tests are **pure math** - no `requestAnimationFrame`, no DOM, no browser APIs
+- Tests can run in Node.js
+- The math is isolated and portable
+- Following `snake_case` convention per AGENTS.md guidelines
+
+## Success Criteria
+
+A correct arcball implementation should:
+1. Pass all 36 tests
+2. Feel smooth and intuitive when dragging
+3. Never produce NaN or invalid rotations
+4. Handle edge cases gracefully
+5. Maintain mathematical invariants (unit quaternions, orthogonal matrices)
+
+---
+
+**This implementation works correctly.** The tests validate the math. Use these tests to verify implementations in other projects.

package/examples/controls/14d) window, canvas globe/EarthGlobeRenderer.js

@@ -1,12 +1,4 @@
-const {
-  qIdentity,
-  qNormalize,
-  qMul,
-  qFromAxisAngle,
-  qFromVectors,
-  mat3FromQuat,
-  mat3Transpose
-} = require('./math');
+const { mat3FromQuat, mat3Transpose } = require('./math');
 const {
   RenderingPipeline,
   TransformStage,
@@ -17,6 +9,8 @@ const {
   ComposeStage,
   HUDStage
 } = require('./RenderingPipeline');
+const ArcballDragBehaviour = require('./arcball-drag-behaviour');
+const DragController = require('./drag-controller');
 
 // Approximate simplified continent outlines (lat, lon in degrees)
 const CONTINENT_OUTLINES = {
@@ -72,17 +66,28 @@ class EarthGlobeRenderer {
     this.ctx = canvas.getContext('2d');
     this.opts = JSON.parse(JSON.stringify(DEFAULT_OPTIONS));
     this.setOptions(opts);
-    this.q = qIdentity();
-  this.R = mat3FromQuat(this.q);
-  this.Rt = mat3Transpose(this.R);
+    
+    // Initialize arcball drag behavior
+    this.drag_behaviour = new ArcballDragBehaviour({
+      inertia_friction: this.opts.inertiaFriction,
+      inertia_min_speed: this.opts.inertiaMinSpeed,
+      on_rotation_change: (q, R, Rt) => {
+        this.q = q;
+        this.R = R;
+        this.Rt = Rt;
+      }
+    });
+    
+    // Access quaternion and matrices from behavior
+    this.q = this.drag_behaviour.q;
+    this.R = this.drag_behaviour.R;
+    this.Rt = this.drag_behaviour.Rt;
+    
     this.sun = this._normVec([1,0,0.25]);
     this.pipelineEnabled = true;
   this._fps = 0;
   this._fpsFrames = 0;
   this._fpsLastUpdate = performance.now();
-  this._axis = [0,1,0];
-  this._omega = 0;
-  this._v0 = [0,0,1];
     this.tex = { albedo:null, water:null, ice:null };
     this._samp = { r:0,g:0,b:0 };
     this._initLUTs();
@@ -99,7 +104,23 @@ class EarthGlobeRenderer {
         new HUDStage(this)
       ]
     );
-    this._attachPointerHandlers();
+    
+    // Initialize drag controller
+    this.drag_controller = new DragController(
+      this.canvas,
+      this.drag_behaviour,
+      {
+        padding: this.opts.padding,
+        on_interactive_frame: () => this.render(true),
+        on_drag_end: () => {
+          // Delay final high-quality render to allow inertia to start
+          setTimeout(() => {
+            if (!this.drag_behaviour.omega) this.render(false);
+          }, 120);
+        }
+      }
+    );
+    
     this.resize();
     this.render(false);
   }
@@ -203,99 +224,6 @@ class EarthGlobeRenderer {
     }
   }
 
-  // -------------- Interaction (arcball + inertia) --------------
-  _attachPointerHandlers() {
-    const el = this.canvas;
-    if (getComputedStyle(el).touchAction !== 'none') el.style.touchAction='none';
-    const onDown = (ev) => {
-      this._dragging = true;
-      this._v0 = this._screenToArcball(ev.clientX, ev.clientY);
-      this._omega = 0;
-      this._lastTime = performance.now();
-      try { el.setPointerCapture(ev.pointerId); } catch {}
-    };
-    const onMove = (ev) => {
-      if (!this._dragging) return;
-      const v1 = this._screenToArcball(ev.clientX, ev.clientY);
-      const dq = qFromVectors(this._v0, v1);
-      this.q = qNormalize(qMul(dq, this.q));
-      this._v0 = v1;
-      const now = performance.now();
-      const dt = Math.max(1, now - this._lastTime) / 1000;
-      this._lastTime = now;
-      let angle = 2 * Math.acos(Math.max(-1, Math.min(1, dq[3])));
-      if (angle > Math.PI) angle = 2 * Math.PI - angle;
-      const s = Math.sqrt(1 - dq[3] * dq[3]);
-      if (s < 1e-6) {
-        this._axis[0] = 0; this._axis[1] = 1; this._axis[2] = 0;
-      } else {
-        this._axis[0] = dq[0] / s;
-        this._axis[1] = dq[1] / s;
-        this._axis[2] = dq[2] / s;
-      }
-      this._omega = angle / dt;
-      this._updateRot();
-      this._requestInteractiveFrame();
-    };
-    const onUp = (ev) => {
-      this._dragging = false;
-      try { el.releasePointerCapture(ev.pointerId); } catch {}
-      this._startInertia();
-      setTimeout(() => { if (!this._omega) this.render(false); }, 120);
-    };
-    el.addEventListener('pointerdown', onDown);
-    el.addEventListener('pointermove', onMove);
-    try { el.addEventListener('pointerrawupdate', onMove); } catch {}
-    el.addEventListener('pointerup', onUp);
-    el.addEventListener('pointercancel', onUp);
-    this._ptr={onDown,onMove,onUp};
-  }
-  _startInertia() {
-    if (this._omega <= this.opts.inertiaMinSpeed) return;
-    const friction = this.opts.inertiaFriction; let last=performance.now();
-    const step = (now) => {
-      const dt = Math.max(1, now - last) / 1000;
-      last = now;
-      this._omega *= Math.exp(-friction * dt);
-      if (this._omega <= this.opts.inertiaMinSpeed) {
-        this._omega = 0; this._raf = 0; return;
-      }
-      const dq = qFromAxisAngle(
-        this._axis[0],
-        this._axis[1],
-        this._axis[2],
-        this._omega * dt
-      );
-      this.q = qNormalize(qMul(dq, this.q));
-      this._updateRot();
-      this._requestInteractiveFrame();
-      this._raf = requestAnimationFrame(step);
-    };
-    if (this._raf) cancelAnimationFrame(this._raf); this._raf=requestAnimationFrame(step);
-  }
-  _requestInteractiveFrame() {
-    if (this._pendingInteractive) return;
-    this._pendingInteractive = true;
-    requestAnimationFrame(() => {
-      this._pendingInteractive = false;
-      this.render(true);
-    });
-  }
-
-  _screenToArcball(clientX, clientY) {
-    const rect = this.canvas.getBoundingClientRect();
-    const cx = rect.left + rect.width / 2;
-    const cy = rect.top + rect.height / 2;
-    const pad = this.opts.padding;
-    const r = Math.max(1, Math.min(rect.width, rect.height) / 2 - pad);
-    const x = (clientX - cx) / r;
-    const y = (cy - clientY) / r;
-    const d2 = x * x + y * y;
-    if (d2 <= 1) return [x, y, Math.sqrt(1 - d2)];
-    const inv = 1 / Math.sqrt(d2);
-    return [x * inv, y * inv, 0];
-  }
-
   // -------------- LUTs & shading utilities --------------
   _initLUTs() {
     if (this._lutsInit) return;
@@ -398,10 +326,6 @@ class EarthGlobeRenderer {
     return img;
   }
 
-  _updateRot() {
-    this.R = mat3FromQuat(this.q);
-    this.Rt = mat3Transpose(this.R);
-  }
   _normVec(v) {
     const n = Math.hypot(v[0], v[1], v[2]) || 1;
     return [v[0]/n, v[1]/n, v[2]/n];

package/examples/controls/14d) window, canvas globe/arcball-drag-behaviour.js

@@ -0,0 +1,250 @@
+'use strict';
+
+const DragBehaviourBase = require('./drag-behaviour-base');
+const {
+  qIdentity,
+  qNormalize,
+  qMul,
+  qFromAxisAngle,
+  qFromVectors,
+  mat3FromQuat,
+  mat3Transpose
+} = require('./math');
+
+/**
+ * ArcballDragBehaviour - Implements virtual trackball/arcball rotation
+ * 
+ * This class handles the sophisticated math for arcball-style rotation:
+ * - Converting 2D screen coordinates to 3D arcball surface positions
+ * - Computing quaternion rotations from drag movements
+ * - Managing inertia with axis and angular velocity
+ * 
+ * The arcball technique allows intuitive 3D rotation by mapping 2D mouse
+ * movements to rotations on a virtual sphere.
+ */
+class ArcballDragBehaviour extends DragBehaviourBase {
+  constructor(options = {}) {
+    super();
+    
+    // Quaternion representing current rotation
+    this.q = qIdentity();
+    
+    // Rotation matrices (derived from quaternion)
+    this.R = mat3FromQuat(this.q);
+    this.Rt = mat3Transpose(this.R);
+    
+    // Previous arcball position (3D vector on unit sphere)
+    this.v0 = [0, 0, 1];
+    
+    // Inertia state
+    this.omega = 0;           // Angular velocity (rad/s)
+    this.axis = [0, 1, 0];    // Rotation axis
+    this.inertia_raf = 0;     // RequestAnimationFrame handle
+    
+    // Options
+    this.inertia_friction = options.inertia_friction || 1.7;
+    this.inertia_min_speed = options.inertia_min_speed || 0.25;
+    
+    // Callbacks
+    this.on_rotation_change = options.on_rotation_change || null;
+  }
+
+  /**
+   * Convert 2D screen position to 3D point on arcball sphere
+   * 
+   * Maps (x, y) in normalized coordinates [-1, 1] to a point on or inside
+   * a unit sphere. Points outside the sphere are projected onto it.
+   * 
+   * @param {number} x - Normalized X coordinate [-1, 1]
+   * @param {number} y - Normalized Y coordinate [-1, 1]
+   * @returns {Array<number>} [x, y, z] point on unit sphere
+   */
+  screen_to_arcball(x, y) {
+    const d2 = x * x + y * y;
+    
+    if (d2 <= 1) {
+      // Inside sphere: compute Z using sphere equation x² + y² + z² = 1
+      return [x, y, Math.sqrt(1 - d2)];
+    }
+    
+    // Outside sphere: normalize to edge
+    const inv = 1 / Math.sqrt(d2);
+    return [x * inv, y * inv, 0];
+  }
+
+  /**
+   * Start drag operation
+   * @param {Object} position - {x, y} normalized coordinates
+   */
+  on_drag_start(position) {
+    super.on_drag_start(position);
+    this.v0 = this.screen_to_arcball(position.x, position.y);
+    this.omega = 0;
+    this.stop_inertia();
+  }
+
+  /**
+   * Update rotation during drag
+   * @param {Object} position - {x, y} normalized coordinates
+   */
+  on_drag_move(position) {
+    const delta_time = super.on_drag_move(position);
+    if (!this.is_dragging) return;
+    
+    // Current arcball position
+    const v1 = this.screen_to_arcball(position.x, position.y);
+    
+    // Compute rotation quaternion from v0 to v1
+    const dq = qFromVectors(this.v0, v1);
+    
+    // Compose with existing rotation: q = dq * q
+    this.q = qNormalize(qMul(dq, this.q));
+    
+    // Update for next frame
+    this.v0 = v1;
+    
+    // Calculate angular velocity for inertia
+    let angle = 2 * Math.acos(Math.max(-1, Math.min(1, dq[3])));
+    if (angle > Math.PI) angle = 2 * Math.PI - angle;
+    
+    // Extract rotation axis from quaternion
+    const s = Math.sqrt(1 - dq[3] * dq[3]);
+    if (s < 1e-6) {
+      this.axis[0] = 0;
+      this.axis[1] = 1;
+      this.axis[2] = 0;
+    } else {
+      this.axis[0] = dq[0] / s;
+      this.axis[1] = dq[1] / s;
+      this.axis[2] = dq[2] / s;
+    }
+    
+    this.omega = angle / delta_time;
+    
+    // Update rotation matrices
+    this._update_rotation_matrices();
+    
+    // Notify callback
+    if (this.on_rotation_change) {
+      this.on_rotation_change(this.q, this.R, this.Rt);
+    }
+  }
+
+  /**
+   * End drag operation and potentially start inertia
+   */
+  on_drag_end() {
+    super.on_drag_end();
+    this.start_inertia();
+  }
+
+  /**
+   * Start inertia animation with exponential decay
+   * @returns {boolean} True if inertia was started
+   */
+  start_inertia() {
+    if (this.omega <= this.inertia_min_speed) {
+      return false;
+    }
+    
+    // Check if requestAnimationFrame is available (not in Node.js)
+    if (typeof requestAnimationFrame === 'undefined') {
+      return false;
+    }
+    
+    const friction = this.inertia_friction;
+    let last = performance.now();
+    
+    const step = (now) => {
+      const dt = Math.max(1, now - last) / 1000;
+      last = now;
+      
+      // Exponential decay
+      this.omega *= Math.exp(-friction * dt);
+      
+      if (this.omega <= this.inertia_min_speed) {
+        this.omega = 0;
+        this.inertia_raf = 0;
+        return;
+      }
+      
+      // Apply incremental rotation
+      const dq = qFromAxisAngle(
+        this.axis[0],
+        this.axis[1],
+        this.axis[2],
+        this.omega * dt
+      );
+      
+      this.q = qNormalize(qMul(dq, this.q));
+      this._update_rotation_matrices();
+      
+      // Notify callback
+      if (this.on_rotation_change) {
+        this.on_rotation_change(this.q, this.R, this.Rt);
+      }
+      
+      this.inertia_raf = requestAnimationFrame(step);
+    };
+    
+    if (this.inertia_raf) cancelAnimationFrame(this.inertia_raf);
+    this.inertia_raf = requestAnimationFrame(step);
+    
+    return true;
+  }
+
+  /**
+   * Stop inertia animation
+   */
+  stop_inertia() {
+    if (this.inertia_raf) {
+      cancelAnimationFrame(this.inertia_raf);
+      this.inertia_raf = 0;
+    }
+    this.omega = 0;
+  }
+
+  /**
+   * Update rotation matrices from quaternion
+   * @private
+   */
+  _update_rotation_matrices() {
+    this.R = mat3FromQuat(this.q);
+    this.Rt = mat3Transpose(this.R);
+  }
+
+  /**
+   * Set quaternion directly (useful for initialization)
+   * @param {Array<number>} q - Quaternion [x, y, z, w]
+   */
+  set_quaternion(q) {
+    this.q = q.slice(); // Copy
+    this._update_rotation_matrices();
+  }
+
+  /**
+   * Get current quaternion
+   * @returns {Array<number>} Quaternion [x, y, z, w]
+   */
+  get_quaternion() {
+    return this.q.slice();
+  }
+
+  /**
+   * Get rotation matrix
+   * @returns {Array<number>} 3x3 matrix (column-major)
+   */
+  get_rotation_matrix() {
+    return this.R.slice();
+  }
+
+  /**
+   * Get transposed rotation matrix
+   * @returns {Array<number>} 3x3 matrix (column-major)
+   */
+  get_rotation_matrix_transpose() {
+    return this.Rt.slice();
+  }
+}
+
+module.exports = ArcballDragBehaviour;

package/examples/controls/14d) window, canvas globe/arcball-drag-behaviour.test.js

@@ -0,0 +1,141 @@
+'use strict';
+const assert = require('assert');
+const ArcballDragBehaviour = require('./arcball-drag-behaviour');
+
+describe('Arcball Core Math', function() {
+  const EPS = 1e-9;
+  const approx = (a, b, e=EPS) => Math.abs(a - b) < e;
+  const approx_arr = (a, b, e=EPS) => a.length === b.length && a.every((v, i) => approx(v, b[i], e));
+  const apply_mat = (m, v) => [m[0]*v[0]+m[3]*v[1]+m[6]*v[2], m[1]*v[0]+m[4]*v[1]+m[7]*v[2], m[2]*v[0]+m[5]*v[1]+m[8]*v[2]];
+  const vec_len = (v) => Math.sqrt(v[0]*v[0] + v[1]*v[1] + v[2]*v[2]);
+  const q_len = (q) => Math.sqrt(q[0]*q[0] + q[1]*q[1] + q[2]*q[2] + q[3]*q[3]);
+
+  describe('screen_to_arcball', function() {
+    let b;
+    beforeEach(() => b = new ArcballDragBehaviour());
+
+    it('center to front [0,0,1]', () => {
+      assert(approx_arr(b.screen_to_arcball(0, 0), [0, 0, 1]));
+    });
+
+    it('all points on unit sphere', () => {
+      [[0,0], [0.5,0], [0,0.5], [0.7,0.7], [1,0], [2,0], [5,5]].forEach(([x,y]) => {
+        assert(approx(vec_len(b.screen_to_arcball(x, y)), 1.0));
+      });
+    });
+
+    it('inside point satisfies sphere equation', () => {
+      const p = b.screen_to_arcball(0.5, 0.5);
+      assert(approx(p[0], 0.5) && approx(p[1], 0.5) && approx(p[2], Math.sqrt(0.5)));
+    });
+
+    it('outside points have z0', () => {
+      const p = b.screen_to_arcball(3, 4);
+      assert(approx(p[2], 0, 1e-6));
+    });
+  });
+
+  describe('drag rotation', function() {
+    let b;
+    beforeEach(() => b = new ArcballDragBehaviour());
+
+    it('horizontal drag preserves Y', () => {
+      b.on_drag_start({x:0, y:0});
+      b.on_drag_move({x:0.5, y:0});
+      const rot = apply_mat(b.get_rotation_matrix(), [1,0,0]);
+      assert(approx(rot[1], 0, 1e-6));
+    });
+
+    it('vertical drag preserves X', () => {
+      b.on_drag_start({x:0, y:0});
+      b.on_drag_move({x:0, y:0.5});
+      const rot = apply_mat(b.get_rotation_matrix(), [0,1,0]);
+      assert(approx(rot[0], 0, 1e-6));
+    });
+
+    it('preserves vector lengths', () => {
+      b.on_drag_start({x:0, y:0});
+      b.on_drag_move({x:0.6, y:0.4});
+      const R = b.get_rotation_matrix();
+      [[1,0,0], [0,1,0], [0,0,1]].forEach(v => {
+        assert(approx(vec_len(v), vec_len(apply_mat(R, v))));
+      });
+    });
+
+    it('maintains unit quaternion after multiple drags', () => {
+      b.on_drag_start({x:0, y:0});
+      b.on_drag_move({x:0.2, y:0});
+      assert(approx(q_len(b.get_quaternion()), 1.0), 'After 1st drag');
+      b.on_drag_move({x:0.4, y:0.1});
+      assert(approx(q_len(b.get_quaternion()), 1.0), 'After 2nd drag');
+      b.on_drag_move({x:0.6, y:0.2});
+      assert(approx(q_len(b.get_quaternion()), 1.0), 'After 3rd drag');
+    });
+
+    it('produces orthogonal matrices', () => {
+      b.on_drag_start({x:0, y:0});
+      b.on_drag_move({x:0.7, y:0.5});
+      const R = b.get_rotation_matrix();
+      const Rt = b.get_rotation_matrix_transpose();
+      const I = [];
+      for (let i=0; i<3; i++) for (let j=0; j<3; j++) {
+        let sum = 0;
+        for (let k=0; k<3; k++) sum += R[k*3+i] * Rt[j*3+k];
+        I.push(sum);
+      }
+      assert(approx_arr(I, [1,0,0,0,1,0,0,0,1]));
+    });
+  });
+
+  describe('edge cases', function() {
+    let b;
+    beforeEach(() => b = new ArcballDragBehaviour());
+
+    it('zero drag no rotation', () => {
+      b.on_drag_start({x:0.3, y:0.3});
+      b.on_drag_move({x:0.3, y:0.3});
+      assert(approx_arr(b.get_quaternion(), [0,0,0,1], 1e-6));
+    });
+
+    it('tiny drag no NaN', () => {
+      b.on_drag_start({x:0, y:0});
+      b.on_drag_move({x:1e-8, y:0});
+      const q = b.get_quaternion();
+      assert(!q.some(isNaN), 'No NaN values');
+      assert(approx(q_len(q), 1.0), 'Unit quaternion');
+    });
+
+    it('large drag stable', () => {
+      b.on_drag_start({x:0, y:0});
+      b.on_drag_move({x:10, y:10});
+      const q = b.get_quaternion();
+      assert(!q.some(isNaN), 'No NaN values');
+      assert(approx(q_len(q), 1.0), 'Unit quaternion');
+    });
+
+    it('rapid direction changes', () => {
+      b.on_drag_start({x:0, y:0});
+      [{ x:0.5, y:0}, {x:0, y:0.5}, {x:-0.5, y:0}, {x:0, y:-0.5}].forEach(pos => {
+        b.on_drag_move(pos);
+        const q = b.get_quaternion();
+        assert(!q.some(isNaN) && approx(q_len(q), 1.0));
+      });
+    });
+  });
+
+  describe('angular velocity', () => {
+    it('drag produces omega', () => {
+      const b = new ArcballDragBehaviour();
+      b.on_drag_start({x:0, y:0});
+      b.on_drag_move({x:0.5, y:0});
+      assert(b.omega > 0 && b.axis.length === 3);
+    });
+
+    it('exponential decay math', () => {
+      let omega = 2.0;
+      const dt = 0.016, friction = 1.7;
+      for (let i=0; i<10; i++) omega *= Math.exp(-friction * dt);
+      assert(omega < 2.0 && omega > 0 && approx(omega, 2.0 * Math.exp(-friction * dt * 10)));
+    });
+  });
+});

package/examples/controls/14d) window, canvas globe/drag-behaviour-base.js

@@ -0,0 +1,70 @@
+'use strict';
+
+/**
+ * DragBehaviourBase - Base class for drag behaviors
+ * 
+ * Provides common functionality for drag interactions including:
+ * - Drag state tracking (is_dragging flag)
+ * - Timing for velocity calculations
+ * - Lifecycle hooks for subclasses to implement
+ * 
+ * Subclasses should override:
+ * - on_drag_start(position) - called when drag begins
+ * - on_drag_move(position, delta_time) - called during drag
+ * - on_drag_end() - called when drag ends
+ * - start_inertia() - called to initiate inertia animation (optional)
+ */
+class DragBehaviourBase {
+  constructor() {
+    this.is_dragging = false;
+    this.last_time = 0;
+  }
+
+  /**
+   * Called when drag operation starts
+   * @param {Object} position - Position info (e.g., screen coords, normalized coords)
+   */
+  on_drag_start(position) {
+    this.is_dragging = true;
+    this.last_time = performance.now();
+  }
+
+  /**
+   * Called during drag operation
+   * @param {Object} position - Current position
+   * @returns {number} Delta time in seconds since last move
+   */
+  on_drag_move(position) {
+    if (!this.is_dragging) return 0;
+    
+    const now = performance.now();
+    const delta_time = Math.max(1, now - this.last_time) / 1000;
+    this.last_time = now;
+    
+    return delta_time;
+  }
+
+  /**
+   * Called when drag operation ends
+   */
+  on_drag_end() {
+    this.is_dragging = false;
+  }
+
+  /**
+   * Override to implement inertia/momentum animation
+   * @returns {boolean} True if inertia was started
+   */
+  start_inertia() {
+    return false;
+  }
+
+  /**
+   * Override to stop any ongoing inertia animation
+   */
+  stop_inertia() {
+    // Base implementation does nothing
+  }
+}
+
+module.exports = DragBehaviourBase;

package/examples/controls/14d) window, canvas globe/drag-controller.js

@@ -0,0 +1,181 @@
+'use strict';
+
+/**
+ * DragController - Handles UI wiring for drag interactions
+ * 
+ * This class manages:
+ * - DOM event attachment (pointerdown, pointermove, pointerup, etc.)
+ * - Pointer capture for reliable tracking
+ * - Coordinate transformation (screen to normalized)
+ * - Delegation to a DragBehaviour instance
+ * 
+ * Separates UI concerns from the mathematical drag behavior logic.
+ */
+class DragController {
+  /**
+   * @param {HTMLElement} element - The element to attach pointer events to
+   * @param {DragBehaviourBase} behaviour - The drag behavior instance
+   * @param {Object} options - Configuration options
+   * @param {number} options.padding - Padding around the arcball area
+   * @param {Function} options.on_interactive_frame - Called to request render during interaction
+   * @param {Function} options.on_drag_end - Called after drag ends (optional)
+   */
+  constructor(element, behaviour, options = {}) {
+    this.element = element;
+    this.behaviour = behaviour;
+    this.padding = options.padding || 8;
+    this.on_interactive_frame = options.on_interactive_frame || null;
+    this.on_drag_end = options.on_drag_end || null;
+    
+    this.dragging = false;
+    this.pending_interactive = false;
+    
+    // Bind event handlers
+    this._on_pointer_down = this._handle_pointer_down.bind(this);
+    this._on_pointer_move = this._handle_pointer_move.bind(this);
+    this._on_pointer_up = this._handle_pointer_up.bind(this);
+    
+    this._attach_handlers();
+  }
+
+  /**
+   * Attach pointer event handlers to the element
+   * @private
+   */
+  _attach_handlers() {
+    const el = this.element;
+    
+    // Ensure touch-action is set for proper touch handling
+    if (getComputedStyle(el).touchAction !== 'none') {
+      el.style.touchAction = 'none';
+    }
+    
+    el.addEventListener('pointerdown', this._on_pointer_down);
+    el.addEventListener('pointermove', this._on_pointer_move);
+    
+    // Try to use pointerrawupdate for higher frequency updates
+    try {
+      el.addEventListener('pointerrawupdate', this._on_pointer_move);
+    } catch (e) {
+      // pointerrawupdate not supported, fall back to pointermove
+    }
+    
+    el.addEventListener('pointerup', this._on_pointer_up);
+    el.addEventListener('pointercancel', this._on_pointer_up);
+  }
+
+  /**
+   * Handle pointer down event
+   * @private
+   */
+  _handle_pointer_down(ev) {
+    this.dragging = true;
+    
+    const pos = this._screen_to_normalized(ev.clientX, ev.clientY);
+    this.behaviour.on_drag_start(pos);
+    
+    // Capture the pointer for reliable tracking
+    try {
+      this.element.setPointerCapture(ev.pointerId);
+    } catch (e) {
+      // Pointer capture may fail in some contexts
+    }
+  }
+
+  /**
+   * Handle pointer move event
+   * @private
+   */
+  _handle_pointer_move(ev) {
+    if (!this.dragging) return;
+    
+    const pos = this._screen_to_normalized(ev.clientX, ev.clientY);
+    this.behaviour.on_drag_move(pos);
+    
+    this._request_interactive_frame();
+  }
+
+  /**
+   * Handle pointer up/cancel event
+   * @private
+   */
+  _handle_pointer_up(ev) {
+    if (!this.dragging) return;
+    
+    this.dragging = false;
+    
+    // Release pointer capture
+    try {
+      this.element.releasePointerCapture(ev.pointerId);
+    } catch (e) {
+      // May fail if capture was not set
+    }
+    
+    this.behaviour.on_drag_end();
+    
+    // Call optional callback
+    if (this.on_drag_end) {
+      this.on_drag_end();
+    }
+  }
+
+  /**
+   * Convert screen coordinates to normalized arcball coordinates
+   * @param {number} clientX - Screen X coordinate
+   * @param {number} clientY - Screen Y coordinate
+   * @returns {Object} {x, y} in normalized space [-1, 1]
+   * @private
+   */
+  _screen_to_normalized(clientX, clientY) {
+    const rect = this.element.getBoundingClientRect();
+    const cx = rect.left + rect.width / 2;
+    const cy = rect.top + rect.height / 2;
+    const r = Math.max(1, Math.min(rect.width, rect.height) / 2 - this.padding);
+    
+    const x = (clientX - cx) / r;
+    const y = (cy - clientY) / r; // Invert Y for standard 3D coordinates
+    
+    return { x, y };
+  }
+
+  /**
+   * Request an interactive frame render
+   * @private
+   */
+  _request_interactive_frame() {
+    if (this.pending_interactive) return;
+    if (!this.on_interactive_frame) return;
+    
+    this.pending_interactive = true;
+    requestAnimationFrame(() => {
+      this.pending_interactive = false;
+      if (this.on_interactive_frame) {
+        this.on_interactive_frame();
+      }
+    });
+  }
+
+  /**
+   * Detach all event handlers
+   */
+  destroy() {
+    const el = this.element;
+    el.removeEventListener('pointerdown', this._on_pointer_down);
+    el.removeEventListener('pointermove', this._on_pointer_move);
+    el.removeEventListener('pointerrawupdate', this._on_pointer_move);
+    el.removeEventListener('pointerup', this._on_pointer_up);
+    el.removeEventListener('pointercancel', this._on_pointer_up);
+    
+    this.behaviour.stop_inertia();
+  }
+
+  /**
+   * Update padding (e.g., when canvas resizes)
+   * @param {number} padding - New padding value
+   */
+  set_padding(padding) {
+    this.padding = padding;
+  }
+}
+
+module.exports = DragController;

package/examples/controls/14d) window, canvas globe/math.test.js

@@ -0,0 +1,281 @@
+'use strict';
+
+const assert = require('assert');
+const {
+  qIdentity,
+  qNormalize,
+  qMul,
+  qFromAxisAngle,
+  qFromVectors,
+  mat3FromQuat,
+  mat3Transpose
+} = require('./math');
+
+describe('Quaternion Math Functions', function() {
+  
+  // Helper to check if two numbers are approximately equal
+  function approx_equal(a, b, epsilon = 1e-10) {
+    return Math.abs(a - b) < epsilon;
+  }
+  
+  // Helper to check if two arrays are approximately equal
+  function approx_equal_array(a, b, epsilon = 1e-10) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!approx_equal(a[i], b[i], epsilon)) return false;
+    }
+    return true;
+  }
+  
+  // Helper to compute quaternion magnitude
+  function q_magnitude(q) {
+    return Math.sqrt(q[0]*q[0] + q[1]*q[1] + q[2]*q[2] + q[3]*q[3]);
+  }
+  
+  describe('qIdentity', function() {
+    it('should return identity quaternion [0, 0, 0, 1]', function() {
+      const q = qIdentity();
+      assert.deepStrictEqual(q, [0, 0, 0, 1]);
+    });
+  });
+  
+  describe('qNormalize', function() {
+    it('should normalize a quaternion to unit length', function() {
+      const q = [1, 2, 3, 4];
+      const normalized = qNormalize(q);
+      const mag = q_magnitude(normalized);
+      assert(approx_equal(mag, 1.0), `Magnitude should be 1.0, got ${mag}`);
+    });
+    
+    it('should handle zero quaternion gracefully', function() {
+      const q = [0, 0, 0, 0];
+      const normalized = qNormalize(q);
+      // Should normalize to [0,0,0,0] since magnitude is 0
+      assert.deepStrictEqual(normalized, [0, 0, 0, 0]);
+    });
+    
+    it('should preserve already normalized quaternions', function() {
+      const q = qIdentity();
+      const normalized = qNormalize(q);
+      assert(approx_equal_array(normalized, [0, 0, 0, 1]));
+    });
+  });
+  
+  describe('qMul', function() {
+    it('should multiply two quaternions correctly', function() {
+      // Identity * anything = anything
+      const q1 = qIdentity();
+      const q2 = [1, 2, 3, 4];
+      const result = qMul(q1, q2);
+      assert(approx_equal_array(result, q2, 1e-9));
+    });
+    
+    it('should be non-commutative (q1*q2 != q2*q1 in general)', function() {
+      const q1 = qFromAxisAngle(1, 0, 0, Math.PI / 4);
+      const q2 = qFromAxisAngle(0, 1, 0, Math.PI / 4);
+      const r1 = qMul(q1, q2);
+      const r2 = qMul(q2, q1);
+      
+      // These should not be equal
+      const are_equal = approx_equal_array(r1, r2, 1e-6);
+      assert(!are_equal, 'Quaternion multiplication should be non-commutative');
+    });
+    
+    it('should compose rotations correctly', function() {
+      // 90° rotation around Z-axis
+      const q1 = qFromAxisAngle(0, 0, 1, Math.PI / 2);
+      // Another 90° rotation around Z-axis
+      const q2 = qFromAxisAngle(0, 0, 1, Math.PI / 2);
+      // Combined should be 180° around Z-axis
+      const result = qNormalize(qMul(q1, q2));
+      const expected = qFromAxisAngle(0, 0, 1, Math.PI);
+      
+      // Allow for both q and -q (they represent same rotation)
+      const match = approx_equal_array(result, expected, 1e-9) ||
+                    approx_equal_array(result, [-expected[0], -expected[1], -expected[2], -expected[3]], 1e-9);
+      assert(match, `Expected ${expected}, got ${result}`);
+    });
+  });
+  
+  describe('qFromAxisAngle', function() {
+    it('should create quaternion from axis-angle', function() {
+      // 180° rotation around X-axis
+      const q = qFromAxisAngle(1, 0, 0, Math.PI);
+      const mag = q_magnitude(q);
+      assert(approx_equal(mag, 1.0), 'Quaternion should be unit length');
+      assert(approx_equal(q[0], 1.0, 1e-9), 'X component should be ~1');
+      assert(approx_equal(q[3], 0.0, 1e-9), 'W component should be ~0');
+    });
+    
+    it('should handle zero angle (identity)', function() {
+      const q = qFromAxisAngle(1, 0, 0, 0);
+      assert(approx_equal_array(q, [0, 0, 0, 1], 1e-9));
+    });
+    
+    it('should normalize axis internally', function() {
+      // Non-unit axis
+      const q = qFromAxisAngle(3, 4, 0, Math.PI / 2);
+      const mag = q_magnitude(q);
+      assert(approx_equal(mag, 1.0), 'Result should be unit quaternion');
+    });
+  });
+  
+  describe('qFromVectors', function() {
+    it('should create quaternion rotating u to v', function() {
+      const u = [1, 0, 0];
+      const v = [0, 1, 0];
+      const q = qFromVectors(u, v);
+      
+      // Verify it's a unit quaternion
+      const mag = q_magnitude(q);
+      assert(approx_equal(mag, 1.0), 'Should be unit quaternion');
+    });
+    
+    it('should handle identical vectors (no rotation)', function() {
+      const u = [1, 0, 0];
+      const v = [1, 0, 0];
+      const q = qFromVectors(u, v);
+      
+      // Should be identity or very close
+      assert(approx_equal_array(q, [0, 0, 0, 1], 1e-9));
+    });
+    
+    it('should handle opposite vectors (180° rotation)', function() {
+      const u = [1, 0, 0];
+      const v = [-1, 0, 0];
+      const q = qFromVectors(u, v);
+      
+      // Should be a 180° rotation
+      const mag = q_magnitude(q);
+      assert(approx_equal(mag, 1.0), 'Should be unit quaternion');
+      // W component should be ~0 for 180° rotation
+      assert(approx_equal(Math.abs(q[3]), 0.0, 1e-9));
+    });
+    
+    it('should handle small angle rotations robustly', function() {
+      const u = [1, 0, 0];
+      const v = [0.99999, 0.00001, 0];
+      // Normalize v
+      const vn = Math.sqrt(v[0]*v[0] + v[1]*v[1] + v[2]*v[2]);
+      v[0] /= vn; v[1] /= vn; v[2] /= vn;
+      
+      const q = qFromVectors(u, v);
+      const mag = q_magnitude(q);
+      assert(approx_equal(mag, 1.0), 'Should be unit quaternion');
+    });
+  });
+  
+  describe('mat3FromQuat', function() {
+    it('should create rotation matrix from quaternion', function() {
+      const q = qIdentity();
+      const m = mat3FromQuat(q);
+      
+      // Identity quaternion should give identity matrix
+      const identity = [
+        1, 0, 0,
+        0, 1, 0,
+        0, 0, 1
+      ];
+      assert(approx_equal_array(m, identity, 1e-9));
+    });
+    
+    it('should create correct matrix for 90° Z rotation', function() {
+      const q = qFromAxisAngle(0, 0, 1, Math.PI / 2);
+      const m = mat3FromQuat(q);
+      
+      // 90° Z rotation matrix (column-major)
+      const expected = [
+        0, 1, 0,
+        -1, 0, 0,
+        0, 0, 1
+      ];
+      assert(approx_equal_array(m, expected, 1e-9));
+    });
+    
+    it('should produce orthogonal matrix', function() {
+      const q = qNormalize([1, 2, 3, 4]);
+      const m = mat3FromQuat(q);
+      
+      // Check if M * M^T = I (orthogonality test)
+      const mt = mat3Transpose(m);
+      
+      // Multiply M * M^T (both are column-major)
+      const result = [];
+      for (let row = 0; row < 3; row++) {
+        for (let col = 0; col < 3; col++) {
+          let sum = 0;
+          for (let k = 0; k < 3; k++) {
+            // m is column-major: element at (row, k) is m[k*3 + row]
+            // mt is column-major: element at (k, col) is mt[col*3 + k]
+            sum += m[k * 3 + row] * mt[col * 3 + k];
+          }
+          result.push(sum);
+        }
+      }
+      
+      const identity = [1, 0, 0, 0, 1, 0, 0, 0, 1];
+      assert(approx_equal_array(result, identity, 1e-9));
+    });
+  });
+  
+  describe('mat3Transpose', function() {
+    it('should transpose a 3x3 matrix', function() {
+      const m = [
+        1, 2, 3,
+        4, 5, 6,
+        7, 8, 9
+      ];
+      const mt = mat3Transpose(m);
+      const expected = [
+        1, 4, 7,
+        2, 5, 8,
+        3, 6, 9
+      ];
+      assert.deepStrictEqual(mt, expected);
+    });
+    
+    it('should be self-inverse (transpose twice = original)', function() {
+      const m = [1, 2, 3, 4, 5, 6, 7, 8, 9];
+      const mt = mat3Transpose(m);
+      const mtt = mat3Transpose(mt);
+      assert.deepStrictEqual(mtt, m);
+    });
+  });
+  
+  describe('Integration Tests', function() {
+    it('should rotate a vector correctly using quaternion', function() {
+      // Rotate point [1,0,0] by 90° around Z-axis
+      // Should get [0,1,0]
+      const q = qFromAxisAngle(0, 0, 1, Math.PI / 2);
+      const m = mat3FromQuat(q);
+      
+      const v = [1, 0, 0];
+      const result = [
+        m[0] * v[0] + m[3] * v[1] + m[6] * v[2],
+        m[1] * v[0] + m[4] * v[1] + m[7] * v[2],
+        m[2] * v[0] + m[5] * v[1] + m[8] * v[2]
+      ];
+      
+      assert(approx_equal_array(result, [0, 1, 0], 1e-9));
+    });
+    
+    it('should compose multiple rotations correctly', function() {
+      // Rotate 90° around X, then 90° around Y
+      const qx = qFromAxisAngle(1, 0, 0, Math.PI / 2);
+      const qy = qFromAxisAngle(0, 1, 0, Math.PI / 2);
+      const qCombined = qNormalize(qMul(qy, qx));
+      
+      // Apply to point [1, 0, 0]
+      const m = mat3FromQuat(qCombined);
+      const v = [1, 0, 0];
+      const result = [
+        m[0] * v[0] + m[3] * v[1] + m[6] * v[2],
+        m[1] * v[0] + m[4] * v[1] + m[7] * v[2],
+        m[2] * v[0] + m[5] * v[1] + m[8] * v[2]
+      ];
+      
+      // Should get [0, 0, -1] (or close to it)
+      assert(approx_equal_array(result, [0, 0, -1], 1e-9));
+    });
+  });
+});

package/package.json

@@ -7,14 +7,14 @@
     "@babel/generator": "^7.28.3",
     "@babel/parser": "^7.28.4",
     "cookies": "^0.9.1",
-    "esbuild": "^0.25.10",
+    "esbuild": "^0.25.11",
     "fnl": "^0.0.36",
     "fnlfs": "^0.0.33",
     "jsgui3-client": "^0.0.120",
     "jsgui3-html": "^0.0.168",
     "jsgui3-webpage": "^0.0.8",
     "jsgui3-website": "^0.0.8",
-    "lang-tools": "^0.0.36",
+    "lang-tools": "^0.0.39",
     "mocha": "^11.7.4",
     "multiparty": "^4.2.3",
     "ncp": "^2.0.0",
@@ -39,7 +39,7 @@
     "type": "git",
     "url": "https://github.com/metabench/jsgui3-server.git"
   },
-  "version": "0.0.135",
+  "version": "0.0.136",
   "scripts": {
     "cli": "node cli.js",
     "serve": "node cli.js serve",

package/resources/local-server-info-resource.js

@@ -81,7 +81,7 @@ class Local_Server_Info extends Resource {
                         callback(null, true);
                     }
 					
-                } else if (o_status == 'on') {
+                } else if (this.status === 'on') {
                     callback(null, true);
                 }
 			}