@rcnr/lockdown 1.0.0 → 1.1.1

package/dist/index.d.mts

@@ -46,18 +46,22 @@ interface UseLockdownReturn {
  * INSTANT SUBMIT (cheating attempts — never accidental):
  *   copy, cut, paste, external drop, devtools shortcuts
  *
- * 2-STRIKE LIMIT (environmental — fullscreen exits only):
- *   Each fullscreen exit starts a 5-second wall-clock countdown to re-enter.
- *   Blur/visibility events during an active countdown are suppressed
- *   (they're a side-effect of being outside fullscreen, not separate offenses).
- *   After the 2nd fullscreen exit, the next exit (or countdown expiry)
- *   triggers instant auto-submit.
+ * 2-STRIKE LIMIT (any focus loss):
+ *   fullscreen_exit, window_blur (Alt+Tab, Win key, Ctrl+N), tab_switch
+ *   ALL burn a strike. After 2 strikes, the next violation auto-submits.
+ *   Fullscreen exits start a 5-second wall-clock countdown to re-enter.
+ *
+ * FOCUS POLLING HEARTBEAT (500ms):
+ *   document.hasFocus() is checked every 500ms as a safety net.
+ *   This catches OS-level actions (Win key, Alt+Tab, notifications)
+ *   that don't reliably fire browser blur/visibility events on Windows.
  *
  * The countdown uses wall-clock timestamps (Date.now()) so freezing
  * JS execution (e.g. via browser task manager) cannot buy extra time.
  *
  * Also blocked (no violation, just prevented):
- *   view source (Ctrl/Cmd+U), print (Ctrl/Cmd+P), context menu (right-click)
+ *   view source (Ctrl/Cmd+U), print (Ctrl/Cmd+P), context menu (right-click),
+ *   Ctrl/Cmd+N (new window), Alt+Tab, Meta/Win key
  *
  * Philosophy: brutally simple. Not Proctorio. Just honest guardrails.
  * If a student makes an honest mistake, the teacher can reset their access.

package/dist/index.d.ts

@@ -46,18 +46,22 @@ interface UseLockdownReturn {
  * INSTANT SUBMIT (cheating attempts — never accidental):
  *   copy, cut, paste, external drop, devtools shortcuts
  *
- * 2-STRIKE LIMIT (environmental — fullscreen exits only):
- *   Each fullscreen exit starts a 5-second wall-clock countdown to re-enter.
- *   Blur/visibility events during an active countdown are suppressed
- *   (they're a side-effect of being outside fullscreen, not separate offenses).
- *   After the 2nd fullscreen exit, the next exit (or countdown expiry)
- *   triggers instant auto-submit.
+ * 2-STRIKE LIMIT (any focus loss):
+ *   fullscreen_exit, window_blur (Alt+Tab, Win key, Ctrl+N), tab_switch
+ *   ALL burn a strike. After 2 strikes, the next violation auto-submits.
+ *   Fullscreen exits start a 5-second wall-clock countdown to re-enter.
+ *
+ * FOCUS POLLING HEARTBEAT (500ms):
+ *   document.hasFocus() is checked every 500ms as a safety net.
+ *   This catches OS-level actions (Win key, Alt+Tab, notifications)
+ *   that don't reliably fire browser blur/visibility events on Windows.
  *
  * The countdown uses wall-clock timestamps (Date.now()) so freezing
  * JS execution (e.g. via browser task manager) cannot buy extra time.
  *
  * Also blocked (no violation, just prevented):
- *   view source (Ctrl/Cmd+U), print (Ctrl/Cmd+P), context menu (right-click)
+ *   view source (Ctrl/Cmd+U), print (Ctrl/Cmd+P), context menu (right-click),
+ *   Ctrl/Cmd+N (new window), Alt+Tab, Meta/Win key
  *
  * Philosophy: brutally simple. Not Proctorio. Just honest guardrails.
  * If a student makes an honest mistake, the teacher can reset their access.

package/dist/index.js

@@ -44,6 +44,8 @@ var DEVTOOLS_KEYS = ["I", "J", "C", "K"];
 var BLUR_SUPPRESS_AFTER_FS_EXIT_MS = 500;
 var FULLSCREEN_REENTRY_SECONDS = 5;
 var MAX_FULLSCREEN_EXITS = 2;
+var FOCUS_POLL_INTERVAL_MS = 500;
+var FOCUS_POLL_COOLDOWN_MS = 2e3;
 function detectMobileDevice() {
   if (typeof navigator === "undefined") return false;
   const hasTouch = navigator.maxTouchPoints > 0;
@@ -78,6 +80,7 @@ function useLockdown({
   const autoSubmittedRef = (0, import_react.useRef)(false);
   const internalDragRef = (0, import_react.useRef)(false);
   const hasEnteredFullscreenRef = (0, import_react.useRef)(false);
+  const lastFocusPollViolationRef = (0, import_react.useRef)(0);
   const onAutoSubmitRef = (0, import_react.useRef)(onAutoSubmit);
   (0, import_react.useEffect)(() => {
     onAutoSubmitRef.current = onAutoSubmit;
@@ -132,7 +135,7 @@ function useLockdown({
         triggerAutoSubmit();
         return;
       }
-      if (type === "fullscreen_exit") {
+      if (type === "fullscreen_exit" || type === "window_blur" || type === "tab_switch") {
         fullscreenExitCountRef.current += 1;
         const remaining = MAX_FULLSCREEN_EXITS - fullscreenExitCountRef.current;
         setStrikesRemaining(remaining);
@@ -141,18 +144,20 @@ function useLockdown({
           triggerAutoSubmit();
         } else if (remaining === 0) {
           setWarning(
-            "Final warning: leave fullscreen again and your work will be auto-submitted."
+            "Final warning: leave this window again and your work will be auto-submitted."
           );
           setTimeout(() => setWarning(null), WARNING_DISPLAY_MS);
+          startCountdown();
         } else {
           setWarning(
-            `Warning: you have ${remaining} chance${remaining > 1 ? "s" : ""} left to re-enter fullscreen.`
+            `Warning: you left the writing window. You have ${remaining} chance${remaining > 1 ? "s" : ""} left.`
           );
           setTimeout(() => setWarning(null), WARNING_DISPLAY_MS);
+          startCountdown();
         }
       }
     },
-    [triggerAutoSubmit]
+    [triggerAutoSubmit, startCountdown]
   );
   const enterFullscreen = (0, import_react.useCallback)(async () => {
     try {
@@ -195,9 +200,6 @@ function useLockdown({
       } else if (!graceRef.current && hasEnteredFullscreenRef.current) {
         lastFsExitRef.current = Date.now();
         addViolation("fullscreen_exit");
-        if (fullscreenExitCountRef.current <= MAX_FULLSCREEN_EXITS) {
-          startCountdown();
-        }
       }
     }
     function handleVisibilityChange() {
@@ -207,7 +209,6 @@ function useLockdown({
     }
     function handleBlur() {
       if (graceRef.current) return;
-      if (countdownIntervalRef.current) return;
       if (Date.now() - lastFsExitRef.current < BLUR_SUPPRESS_AFTER_FS_EXIT_MS)
         return;
       addViolation("window_blur");
@@ -253,6 +254,11 @@ function useLockdown({
         addViolation("devtools_attempt");
         return;
       }
+      if (modKey && e.key.toLowerCase() === "n") {
+        e.preventDefault();
+        addViolation("window_blur");
+        return;
+      }
       if (modKey && e.key.toLowerCase() === "u") {
         e.preventDefault();
         return;
@@ -261,13 +267,27 @@ function useLockdown({
         e.preventDefault();
         return;
       }
+      if (e.altKey && e.key === "Tab") {
+        e.preventDefault();
+        return;
+      }
+      if (e.key === "Meta" || e.key === "OS") {
+        e.preventDefault();
+        return;
+      }
     }
     function handleContextMenu(e) {
       e.preventDefault();
     }
+    function handleFocus() {
+      if (countdownIntervalRef.current) {
+        clearCountdown();
+      }
+    }
     document.addEventListener("fullscreenchange", handleFullscreenChange);
     document.addEventListener("visibilitychange", handleVisibilityChange);
     window.addEventListener("blur", handleBlur);
+    window.addEventListener("focus", handleFocus);
     document.addEventListener("paste", handlePaste);
     document.addEventListener("copy", handleCopy);
     document.addEventListener("cut", handleCut);
@@ -281,6 +301,7 @@ function useLockdown({
       document.removeEventListener("fullscreenchange", handleFullscreenChange);
       document.removeEventListener("visibilitychange", handleVisibilityChange);
       window.removeEventListener("blur", handleBlur);
+      window.removeEventListener("focus", handleFocus);
       document.removeEventListener("paste", handlePaste);
       document.removeEventListener("copy", handleCopy);
       document.removeEventListener("cut", handleCut);
@@ -292,6 +313,24 @@ function useLockdown({
       document.removeEventListener("contextmenu", handleContextMenu);
     };
   }, [enabled, addViolation, startCountdown, clearCountdown]);
+  (0, import_react.useEffect)(() => {
+    if (!enabled) return;
+    const interval = setInterval(() => {
+      if (!hasEnteredFullscreenRef.current) return;
+      if (graceRef.current) return;
+      if (autoSubmittedRef.current) return;
+      if (!document.hasFocus()) {
+        const now = Date.now();
+        if (now - lastFocusPollViolationRef.current < FOCUS_POLL_COOLDOWN_MS)
+          return;
+        if (now - lastFsExitRef.current < BLUR_SUPPRESS_AFTER_FS_EXIT_MS)
+          return;
+        lastFocusPollViolationRef.current = now;
+        addViolation("window_blur");
+      }
+    }, FOCUS_POLL_INTERVAL_MS);
+    return () => clearInterval(interval);
+  }, [enabled, addViolation]);
   return {
     isFullscreen,
     isMobileDevice,

package/dist/index.mjs

@@ -17,6 +17,8 @@ var DEVTOOLS_KEYS = ["I", "J", "C", "K"];
 var BLUR_SUPPRESS_AFTER_FS_EXIT_MS = 500;
 var FULLSCREEN_REENTRY_SECONDS = 5;
 var MAX_FULLSCREEN_EXITS = 2;
+var FOCUS_POLL_INTERVAL_MS = 500;
+var FOCUS_POLL_COOLDOWN_MS = 2e3;
 function detectMobileDevice() {
   if (typeof navigator === "undefined") return false;
   const hasTouch = navigator.maxTouchPoints > 0;
@@ -51,6 +53,7 @@ function useLockdown({
   const autoSubmittedRef = useRef(false);
   const internalDragRef = useRef(false);
   const hasEnteredFullscreenRef = useRef(false);
+  const lastFocusPollViolationRef = useRef(0);
   const onAutoSubmitRef = useRef(onAutoSubmit);
   useEffect(() => {
     onAutoSubmitRef.current = onAutoSubmit;
@@ -105,7 +108,7 @@ function useLockdown({
         triggerAutoSubmit();
         return;
       }
-      if (type === "fullscreen_exit") {
+      if (type === "fullscreen_exit" || type === "window_blur" || type === "tab_switch") {
         fullscreenExitCountRef.current += 1;
         const remaining = MAX_FULLSCREEN_EXITS - fullscreenExitCountRef.current;
         setStrikesRemaining(remaining);
@@ -114,18 +117,20 @@ function useLockdown({
           triggerAutoSubmit();
         } else if (remaining === 0) {
           setWarning(
-            "Final warning: leave fullscreen again and your work will be auto-submitted."
+            "Final warning: leave this window again and your work will be auto-submitted."
           );
           setTimeout(() => setWarning(null), WARNING_DISPLAY_MS);
+          startCountdown();
         } else {
           setWarning(
-            `Warning: you have ${remaining} chance${remaining > 1 ? "s" : ""} left to re-enter fullscreen.`
+            `Warning: you left the writing window. You have ${remaining} chance${remaining > 1 ? "s" : ""} left.`
           );
           setTimeout(() => setWarning(null), WARNING_DISPLAY_MS);
+          startCountdown();
         }
       }
     },
-    [triggerAutoSubmit]
+    [triggerAutoSubmit, startCountdown]
   );
   const enterFullscreen = useCallback(async () => {
     try {
@@ -168,9 +173,6 @@ function useLockdown({
       } else if (!graceRef.current && hasEnteredFullscreenRef.current) {
         lastFsExitRef.current = Date.now();
         addViolation("fullscreen_exit");
-        if (fullscreenExitCountRef.current <= MAX_FULLSCREEN_EXITS) {
-          startCountdown();
-        }
       }
     }
     function handleVisibilityChange() {
@@ -180,7 +182,6 @@ function useLockdown({
     }
     function handleBlur() {
       if (graceRef.current) return;
-      if (countdownIntervalRef.current) return;
       if (Date.now() - lastFsExitRef.current < BLUR_SUPPRESS_AFTER_FS_EXIT_MS)
         return;
       addViolation("window_blur");
@@ -226,6 +227,11 @@ function useLockdown({
         addViolation("devtools_attempt");
         return;
       }
+      if (modKey && e.key.toLowerCase() === "n") {
+        e.preventDefault();
+        addViolation("window_blur");
+        return;
+      }
       if (modKey && e.key.toLowerCase() === "u") {
         e.preventDefault();
         return;
@@ -234,13 +240,27 @@ function useLockdown({
         e.preventDefault();
         return;
       }
+      if (e.altKey && e.key === "Tab") {
+        e.preventDefault();
+        return;
+      }
+      if (e.key === "Meta" || e.key === "OS") {
+        e.preventDefault();
+        return;
+      }
     }
     function handleContextMenu(e) {
       e.preventDefault();
     }
+    function handleFocus() {
+      if (countdownIntervalRef.current) {
+        clearCountdown();
+      }
+    }
     document.addEventListener("fullscreenchange", handleFullscreenChange);
     document.addEventListener("visibilitychange", handleVisibilityChange);
     window.addEventListener("blur", handleBlur);
+    window.addEventListener("focus", handleFocus);
     document.addEventListener("paste", handlePaste);
     document.addEventListener("copy", handleCopy);
     document.addEventListener("cut", handleCut);
@@ -254,6 +274,7 @@ function useLockdown({
       document.removeEventListener("fullscreenchange", handleFullscreenChange);
       document.removeEventListener("visibilitychange", handleVisibilityChange);
       window.removeEventListener("blur", handleBlur);
+      window.removeEventListener("focus", handleFocus);
       document.removeEventListener("paste", handlePaste);
       document.removeEventListener("copy", handleCopy);
       document.removeEventListener("cut", handleCut);
@@ -265,6 +286,24 @@ function useLockdown({
       document.removeEventListener("contextmenu", handleContextMenu);
     };
   }, [enabled, addViolation, startCountdown, clearCountdown]);
+  useEffect(() => {
+    if (!enabled) return;
+    const interval = setInterval(() => {
+      if (!hasEnteredFullscreenRef.current) return;
+      if (graceRef.current) return;
+      if (autoSubmittedRef.current) return;
+      if (!document.hasFocus()) {
+        const now = Date.now();
+        if (now - lastFocusPollViolationRef.current < FOCUS_POLL_COOLDOWN_MS)
+          return;
+        if (now - lastFsExitRef.current < BLUR_SUPPRESS_AFTER_FS_EXIT_MS)
+          return;
+        lastFocusPollViolationRef.current = now;
+        addViolation("window_blur");
+      }
+    }, FOCUS_POLL_INTERVAL_MS);
+    return () => clearInterval(interval);
+  }, [enabled, addViolation]);
   return {
     isFullscreen,
     isMobileDevice,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rcnr/lockdown",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Shared fullscreen lockdown hook for RCNR student frontends",
   "main": "dist/index.js",
   "module": "dist/index.mjs",