Merge pull request #1 from OMARVII/fix/flash-counting-off-by-one

fix: reliable flash detection at threshold frequencies

Author: OMARVII

src/detector.js

@@ -24,8 +24,16 @@ var NeuroShieldDetector = (function () {
   const TARGET_FPS = 15;
   const FRAME_INTERVAL_MS = Math.round(1000 / TARGET_FPS);
 
-  /** Sliding window duration for flash counting (ms). */
-  const WINDOW_DURATION_MS = 1000;
+  /**
+   * Sliding window duration for flash counting (ms).
+   * Extended by one frame interval beyond 1 second so the window reliably
+   * captures transitions at the boundary. Without this, a flash whose
+   * direction change falls right at the 1-second edge is missed ~40% of the
+   * time, causing under-detection at the exact threshold frequency (e.g.
+   * 3 Hz at medium sensitivity).  The extra 67 ms has negligible impact on
+   * false-positive rate (effective threshold shifts from 3.0 Hz to ~2.8 Hz).
+   */
+  const WINDOW_DURATION_MS = 1000 + FRAME_INTERVAL_MS;
 
   /**
    * WCAG general flash threshold.
@@ -329,7 +337,7 @@ var NeuroShieldDetector = (function () {
         return { isFlashing: false, flashCount: 0, isRedFlash: false, peakDelta: 0, severity: 'safe' };
       }
 
-      var transitions = 0;
+      var directionChanges = 0;
       var redTransitions = 0;
       var peakDelta = 0;
       var lastDirection = 0; // +1 = getting brighter, -1 = getting darker
@@ -346,9 +354,11 @@ var NeuroShieldDetector = (function () {
         if (absDelta >= LUMINANCE_DELTA_THRESHOLD && darkerLum < DARK_STATE_THRESHOLD) {
           var direction = delta > 0 ? 1 : -1;
 
-          // Count opposing transitions (direction change)
-          if (lastDirection !== 0 && direction !== lastDirection) {
-            transitions++;
+          // Count every significant direction change, including the first.
+          // The first change starts a potential flash cycle; subsequent
+          // opposing changes continue it. Two direction changes = one flash.
+          if (lastDirection === 0 || direction !== lastDirection) {
+            directionChanges++;
           }
           lastDirection = direction;
 
@@ -360,10 +370,10 @@ var NeuroShieldDetector = (function () {
         }
       }
 
-      // Each flash = 1 full cycle (bright→dark→bright) = 2 opposing transitions
-      // But we count individual opposing transitions, so flashCount ≈ transitions
-      // Being conservative: any opposing transition pair counts
-      var flashCount = Math.ceil(transitions / 2);
+      // Each flash = 1 full cycle (bright→dark→bright) = 2 direction changes.
+      // floor() is used because an incomplete cycle (single direction change)
+      // does not constitute a full flash per WCAG 2.3.1.
+      var flashCount = Math.floor(directionChanges / 2);
       var threshold = SENSITIVITY[this.sensitivity] || SENSITIVITY.medium;
       var isFlashing = flashCount >= threshold;
       var isRedFlash = redTransitions >= 1;

test/detector.test.js

@@ -361,14 +361,13 @@ describe('Flash detection (_analyzeWindow integration)', () => {
   });
 
   it('does NOT trigger at medium for 2 flash cycles but DOES trigger at high', () => {
-    // 2 flash cycles = 4 opposing transitions = ceil(4/2) = 2 flashes
+    // 2 complete cycles: D→B→D→B→D (4 direction changes → floor(4/2)=2)
     const history = [
       { timestamp: 0, luminance: 0.0, redRatio: 0 },
-      { timestamp: 100, luminance: 0.9, redRatio: 0 },   // up
-      { timestamp: 200, luminance: 0.0, redRatio: 0 },   // down (transition 1)
-      { timestamp: 300, luminance: 0.9, redRatio: 0 },   // up (transition 2)
-      { timestamp: 400, luminance: 0.0, redRatio: 0 },   // down (transition 3)
-      { timestamp: 500, luminance: 0.9, redRatio: 0 },   // up (transition 4)
+      { timestamp: 100, luminance: 0.9, redRatio: 0 },   // up (change 1)
+      { timestamp: 200, luminance: 0.0, redRatio: 0 },   // down (change 2)
+      { timestamp: 300, luminance: 0.9, redRatio: 0 },   // up (change 3)
+      { timestamp: 400, luminance: 0.0, redRatio: 0 },   // down (change 4)
     ];
 
     const medDet = createDetectorWithHistory('medium', history);
@@ -382,6 +381,34 @@ describe('Flash detection (_analyzeWindow integration)', () => {
       `high should trigger at ${highResult.flashCount} flashes`);
   });
 
+  it('triggers at maximum for a single complete flash cycle', () => {
+    // 1 complete cycle: D→B→D (2 direction changes → floor(2/2)=1)
+    const history = [
+      { timestamp: 0, luminance: 0.1, redRatio: 0 },
+      { timestamp: 67, luminance: 0.8, redRatio: 0 },
+      { timestamp: 134, luminance: 0.1, redRatio: 0 },
+    ];
+    const det = createDetectorWithHistory('maximum', history);
+    const result = det._analyzeWindow();
+    assert.strictEqual(result.isFlashing, true,
+      `maximum should trigger at ${result.flashCount} flash`);
+    assert.strictEqual(result.flashCount, 1);
+  });
+
+  it('does NOT trigger at maximum for a single direction change (half-cycle)', () => {
+    // Half cycle: D→B only (1 direction change → floor(1/2)=0)
+    const history = [
+      { timestamp: 0, luminance: 0.1, redRatio: 0 },
+      { timestamp: 67, luminance: 0.1, redRatio: 0 },
+      { timestamp: 134, luminance: 0.8, redRatio: 0 },
+    ];
+    const det = createDetectorWithHistory('maximum', history);
+    const result = det._analyzeWindow();
+    assert.strictEqual(result.isFlashing, false,
+      'a single direction change is not a complete flash');
+    assert.strictEqual(result.flashCount, 0);
+  });
+
   it('ignores luminance changes below the 0.1 threshold', () => {
     const history = [];
     for (let i = 0; i < 20; i++) {
@@ -507,6 +534,83 @@ describe('Flash detection (_analyzeWindow integration)', () => {
   });
 });
 
+describe('realistic 15fps simulation', () => {
+  it('detects 3Hz flashing at medium when sampled at 15fps over full window', () => {
+    // Simulate exactly what the real detector sees: 15fps sampling (67ms apart)
+    // over the extended window (1067ms). A 3Hz signal alternates every ~167ms.
+    const fps = 15;
+    const interval = Math.round(1000 / fps);       // 67ms
+    const windowMs = 1000 + interval;               // 1067ms
+    const flashHz = 3;
+    const halfPeriod = 1000 / (flashHz * 2);        // ~167ms per half-cycle
+
+    const history = [];
+    for (let t = 0; t <= windowMs; t += interval) {
+      // Which half-cycle are we in?  Even = dark, odd = bright.
+      const phase = Math.floor(t / halfPeriod);
+      history.push({
+        timestamp: t,
+        luminance: phase % 2 === 0 ? 0.05 : 0.85,
+        redRatio: 0,
+      });
+    }
+
+    const det = createDetectorWithHistory('medium', history);
+    const result = det._analyzeWindow();
+    assert.strictEqual(result.isFlashing, true,
+      `3Hz at medium should trigger (got ${result.flashCount} flashes from ${history.length} frames)`);
+    assert.ok(result.flashCount >= 3,
+      `expected >= 3 flashes, got ${result.flashCount}`);
+  });
+
+  it('does NOT detect 2Hz flashing at medium (below 3Hz threshold)', () => {
+    const fps = 15;
+    const interval = Math.round(1000 / fps);
+    const windowMs = 1000 + interval;
+    const flashHz = 2;
+    const halfPeriod = 1000 / (flashHz * 2);
+
+    const history = [];
+    for (let t = 0; t <= windowMs; t += interval) {
+      const phase = Math.floor(t / halfPeriod);
+      history.push({
+        timestamp: t,
+        luminance: phase % 2 === 0 ? 0.05 : 0.85,
+        redRatio: 0,
+      });
+    }
+
+    const det = createDetectorWithHistory('medium', history);
+    const result = det._analyzeWindow();
+    assert.strictEqual(result.isFlashing, false,
+      `2Hz at medium should NOT trigger (got ${result.flashCount} flashes)`);
+  });
+
+  it('detects 1Hz flashing at maximum sensitivity', () => {
+    const fps = 15;
+    const interval = Math.round(1000 / fps);
+    const windowMs = 1000 + interval;
+    const flashHz = 1;
+    const halfPeriod = 1000 / (flashHz * 2);
+
+    const history = [];
+    for (let t = 0; t <= windowMs; t += interval) {
+      const phase = Math.floor(t / halfPeriod);
+      history.push({
+        timestamp: t,
+        luminance: phase % 2 === 0 ? 0.05 : 0.85,
+        redRatio: 0,
+      });
+    }
+
+    const det = createDetectorWithHistory('maximum', history);
+    const result = det._analyzeWindow();
+    assert.strictEqual(result.isFlashing, true,
+      `1Hz at maximum should trigger (got ${result.flashCount} flashes)`);
+    assert.strictEqual(result.flashCount, 1);
+  });
+});
+
 describe('FlashDetector class', () => {
   it('defaults to medium sensitivity', () => {
     const det = new FlashDetector({ tagName: 'VIDEO' }, {});