@rcnr/lockdown 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,68 @@
+/** A recorded lockdown violation. */
+interface Violation {
+    type: ViolationType;
+    timestamp: number;
+}
+/** All violation types the lockdown hook can detect. */
+type ViolationType = "fullscreen_exit" | "tab_switch" | "window_blur" | "paste_attempt" | "copy_attempt" | "cut_attempt" | "drop_attempt" | "devtools_attempt";
+/** Violations that trigger instant auto-submit (cheating attempts). */
+declare const INSTANT_SUBMIT_VIOLATIONS: Set<ViolationType>;
+/** Configuration for the lockdown hook. */
+interface UseLockdownOptions {
+    /** Whether lockdown enforcement is active. */
+    enabled: boolean;
+    /** Grace period in ms after initial fullscreen entry. Default: 5000. */
+    gracePeriodMs?: number;
+    /** Called when auto-submit is triggered (cheating or strikes exhausted). */
+    onAutoSubmit: () => void;
+    /** Optional callback fired on every violation (e.g. for backend reporting). */
+    onViolation?: (violation: Violation) => void;
+}
+/** Return value from the lockdown hook. */
+interface UseLockdownReturn {
+    /** Whether the browser is currently in fullscreen mode. */
+    isFullscreen: boolean;
+    /** Whether the device is mobile/tablet (cannot support fullscreen lockdown). */
+    isMobileDevice: boolean;
+    /** All recorded violations. */
+    violations: Violation[];
+    /** Current warning message, or null. */
+    warning: string | null;
+    /** Seconds remaining to re-enter fullscreen, or null if in fullscreen. */
+    fullscreenCountdown: number | null;
+    /** How many fullscreen exits remain before auto-submit. */
+    strikesRemaining: number;
+    /** Whether fullscreen has been entered at least once. */
+    hasEnteredFullscreen: boolean;
+    /** Request fullscreen entry. */
+    enterFullscreen: () => Promise<void>;
+}
+
+/**
+ * Lockdown hook — enforces fullscreen environment for student tools.
+ *
+ * Two-tier violation policy:
+ *
+ * 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.
+ *
+ * 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)
+ *
+ * Philosophy: brutally simple. Not Proctorio. Just honest guardrails.
+ * If a student makes an honest mistake, the teacher can reset their access.
+ */
+
+declare function useLockdown({ enabled, gracePeriodMs, onAutoSubmit, onViolation, }: UseLockdownOptions): UseLockdownReturn;
+
+export { INSTANT_SUBMIT_VIOLATIONS, type UseLockdownOptions, type UseLockdownReturn, type Violation, type ViolationType, useLockdown };

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+/** A recorded lockdown violation. */
+interface Violation {
+    type: ViolationType;
+    timestamp: number;
+}
+/** All violation types the lockdown hook can detect. */
+type ViolationType = "fullscreen_exit" | "tab_switch" | "window_blur" | "paste_attempt" | "copy_attempt" | "cut_attempt" | "drop_attempt" | "devtools_attempt";
+/** Violations that trigger instant auto-submit (cheating attempts). */
+declare const INSTANT_SUBMIT_VIOLATIONS: Set<ViolationType>;
+/** Configuration for the lockdown hook. */
+interface UseLockdownOptions {
+    /** Whether lockdown enforcement is active. */
+    enabled: boolean;
+    /** Grace period in ms after initial fullscreen entry. Default: 5000. */
+    gracePeriodMs?: number;
+    /** Called when auto-submit is triggered (cheating or strikes exhausted). */
+    onAutoSubmit: () => void;
+    /** Optional callback fired on every violation (e.g. for backend reporting). */
+    onViolation?: (violation: Violation) => void;
+}
+/** Return value from the lockdown hook. */
+interface UseLockdownReturn {
+    /** Whether the browser is currently in fullscreen mode. */
+    isFullscreen: boolean;
+    /** Whether the device is mobile/tablet (cannot support fullscreen lockdown). */
+    isMobileDevice: boolean;
+    /** All recorded violations. */
+    violations: Violation[];
+    /** Current warning message, or null. */
+    warning: string | null;
+    /** Seconds remaining to re-enter fullscreen, or null if in fullscreen. */
+    fullscreenCountdown: number | null;
+    /** How many fullscreen exits remain before auto-submit. */
+    strikesRemaining: number;
+    /** Whether fullscreen has been entered at least once. */
+    hasEnteredFullscreen: boolean;
+    /** Request fullscreen entry. */
+    enterFullscreen: () => Promise<void>;
+}
+
+/**
+ * Lockdown hook — enforces fullscreen environment for student tools.
+ *
+ * Two-tier violation policy:
+ *
+ * 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.
+ *
+ * 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)
+ *
+ * Philosophy: brutally simple. Not Proctorio. Just honest guardrails.
+ * If a student makes an honest mistake, the teacher can reset their access.
+ */
+
+declare function useLockdown({ enabled, gracePeriodMs, onAutoSubmit, onViolation, }: UseLockdownOptions): UseLockdownReturn;
+
+export { INSTANT_SUBMIT_VIOLATIONS, type UseLockdownOptions, type UseLockdownReturn, type Violation, type ViolationType, useLockdown };

package/dist/index.js

@@ -0,0 +1,310 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  INSTANT_SUBMIT_VIOLATIONS: () => INSTANT_SUBMIT_VIOLATIONS,
+  useLockdown: () => useLockdown
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/useLockdown.ts
+var import_react = require("react");
+
+// src/types.ts
+var INSTANT_SUBMIT_VIOLATIONS = /* @__PURE__ */ new Set([
+  "paste_attempt",
+  "copy_attempt",
+  "cut_attempt",
+  "drop_attempt",
+  "devtools_attempt"
+]);
+
+// src/useLockdown.ts
+var DEFAULT_GRACE_PERIOD_MS = 5e3;
+var WARNING_DISPLAY_MS = 5e3;
+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;
+function detectMobileDevice() {
+  if (typeof navigator === "undefined") return false;
+  const hasTouch = navigator.maxTouchPoints > 0;
+  const isSmallScreen = window.screen.width < 1024;
+  const mobileUA = /Android|iPhone|iPad|iPod|webOS|BlackBerry|Opera Mini|IEMobile/i.test(
+    navigator.userAgent
+  );
+  return mobileUA || hasTouch && isSmallScreen;
+}
+function useLockdown({
+  enabled,
+  gracePeriodMs = DEFAULT_GRACE_PERIOD_MS,
+  onAutoSubmit,
+  onViolation
+}) {
+  const [isFullscreen, setIsFullscreen] = (0, import_react.useState)(false);
+  const [violations, setViolations] = (0, import_react.useState)([]);
+  const [warning, setWarning] = (0, import_react.useState)(null);
+  const [isMobileDevice] = (0, import_react.useState)(() => detectMobileDevice());
+  const [fullscreenCountdown, setFullscreenCountdown] = (0, import_react.useState)(
+    null
+  );
+  const [strikesRemaining, setStrikesRemaining] = (0, import_react.useState)(MAX_FULLSCREEN_EXITS);
+  const [hasEnteredFullscreen, setHasEnteredFullscreen] = (0, import_react.useState)(false);
+  const graceRef = (0, import_react.useRef)(false);
+  const fullscreenExitCountRef = (0, import_react.useRef)(0);
+  const lastFsExitRef = (0, import_react.useRef)(0);
+  const countdownIntervalRef = (0, import_react.useRef)(
+    null
+  );
+  const countdownStartRef = (0, import_react.useRef)(0);
+  const autoSubmittedRef = (0, import_react.useRef)(false);
+  const internalDragRef = (0, import_react.useRef)(false);
+  const hasEnteredFullscreenRef = (0, import_react.useRef)(false);
+  const onAutoSubmitRef = (0, import_react.useRef)(onAutoSubmit);
+  (0, import_react.useEffect)(() => {
+    onAutoSubmitRef.current = onAutoSubmit;
+  }, [onAutoSubmit]);
+  const onViolationRef = (0, import_react.useRef)(onViolation);
+  (0, import_react.useEffect)(() => {
+    onViolationRef.current = onViolation;
+  }, [onViolation]);
+  const triggerAutoSubmit = (0, import_react.useCallback)(() => {
+    if (autoSubmittedRef.current) return;
+    autoSubmittedRef.current = true;
+    onAutoSubmitRef.current();
+  }, []);
+  const clearCountdown = (0, import_react.useCallback)(() => {
+    if (countdownIntervalRef.current) {
+      clearInterval(countdownIntervalRef.current);
+      countdownIntervalRef.current = null;
+    }
+    countdownStartRef.current = 0;
+    setFullscreenCountdown(null);
+  }, []);
+  const startCountdown = (0, import_react.useCallback)(() => {
+    clearCountdown();
+    countdownStartRef.current = Date.now();
+    setFullscreenCountdown(FULLSCREEN_REENTRY_SECONDS);
+    countdownIntervalRef.current = setInterval(() => {
+      const elapsed = (Date.now() - countdownStartRef.current) / 1e3;
+      const remaining = Math.max(
+        0,
+        Math.ceil(FULLSCREEN_REENTRY_SECONDS - elapsed)
+      );
+      setFullscreenCountdown(remaining);
+      if (remaining <= 0) {
+        clearCountdown();
+        triggerAutoSubmit();
+      }
+    }, 500);
+  }, [clearCountdown, triggerAutoSubmit]);
+  (0, import_react.useEffect)(() => {
+    return () => clearCountdown();
+  }, [clearCountdown]);
+  const addViolation = (0, import_react.useCallback)(
+    (type) => {
+      if (graceRef.current) return;
+      if (!hasEnteredFullscreenRef.current) return;
+      if (autoSubmittedRef.current) return;
+      const v = { type, timestamp: Date.now() };
+      setViolations((prev) => [...prev, v]);
+      onViolationRef.current?.(v);
+      if (INSTANT_SUBMIT_VIOLATIONS.has(type)) {
+        setWarning("Your work has been submitted.");
+        triggerAutoSubmit();
+        return;
+      }
+      if (type === "fullscreen_exit") {
+        fullscreenExitCountRef.current += 1;
+        const remaining = MAX_FULLSCREEN_EXITS - fullscreenExitCountRef.current;
+        setStrikesRemaining(remaining);
+        if (remaining < 0) {
+          setWarning("Your work has been submitted.");
+          triggerAutoSubmit();
+        } else if (remaining === 0) {
+          setWarning(
+            "Final warning: leave fullscreen again and your work will be auto-submitted."
+          );
+          setTimeout(() => setWarning(null), WARNING_DISPLAY_MS);
+        } else {
+          setWarning(
+            `Warning: you have ${remaining} chance${remaining > 1 ? "s" : ""} left to re-enter fullscreen.`
+          );
+          setTimeout(() => setWarning(null), WARNING_DISPLAY_MS);
+        }
+      }
+    },
+    [triggerAutoSubmit]
+  );
+  const enterFullscreen = (0, import_react.useCallback)(async () => {
+    try {
+      await document.documentElement.requestFullscreen();
+      setIsFullscreen(true);
+      clearCountdown();
+      if (!hasEnteredFullscreenRef.current) {
+        hasEnteredFullscreenRef.current = true;
+        setHasEnteredFullscreen(true);
+        graceRef.current = true;
+        setTimeout(() => {
+          graceRef.current = false;
+        }, gracePeriodMs);
+      } else {
+        setHasEnteredFullscreen(true);
+      }
+    } catch {
+      if (hasEnteredFullscreenRef.current) {
+        startCountdown();
+      }
+    }
+  }, [gracePeriodMs, clearCountdown, startCountdown]);
+  (0, import_react.useEffect)(() => {
+    if (!enabled) return;
+    function handleBeforeUnload(e) {
+      e.preventDefault();
+    }
+    window.addEventListener("beforeunload", handleBeforeUnload);
+    return () => window.removeEventListener("beforeunload", handleBeforeUnload);
+  }, [enabled]);
+  (0, import_react.useEffect)(() => {
+    if (!enabled) return;
+    function handleFullscreenChange() {
+      const fs = !!document.fullscreenElement;
+      setIsFullscreen(fs);
+      if (fs) {
+        hasEnteredFullscreenRef.current = true;
+        setHasEnteredFullscreen(true);
+        clearCountdown();
+      } else if (!graceRef.current && hasEnteredFullscreenRef.current) {
+        lastFsExitRef.current = Date.now();
+        addViolation("fullscreen_exit");
+        if (fullscreenExitCountRef.current <= MAX_FULLSCREEN_EXITS) {
+          startCountdown();
+        }
+      }
+    }
+    function handleVisibilityChange() {
+      if (document.hidden && !graceRef.current && !countdownIntervalRef.current) {
+        addViolation("tab_switch");
+      }
+    }
+    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");
+    }
+    function handlePaste(e) {
+      e.preventDefault();
+      addViolation("paste_attempt");
+    }
+    function handleCopy(e) {
+      e.preventDefault();
+      addViolation("copy_attempt");
+    }
+    function handleCut(e) {
+      e.preventDefault();
+      addViolation("cut_attempt");
+    }
+    function handleDragStart() {
+      internalDragRef.current = true;
+    }
+    function handleDragEnd() {
+      internalDragRef.current = false;
+    }
+    function handleDrop(e) {
+      if (internalDragRef.current) {
+        internalDragRef.current = false;
+        return;
+      }
+      e.preventDefault();
+      addViolation("drop_attempt");
+    }
+    function handleDragOver(e) {
+      e.preventDefault();
+    }
+    function handleKeydown(e) {
+      const modKey = e.ctrlKey || e.metaKey;
+      if (e.key === "F12") {
+        e.preventDefault();
+        addViolation("devtools_attempt");
+        return;
+      }
+      if (modKey && e.shiftKey && DEVTOOLS_KEYS.includes(e.key.toUpperCase())) {
+        e.preventDefault();
+        addViolation("devtools_attempt");
+        return;
+      }
+      if (modKey && e.key.toLowerCase() === "u") {
+        e.preventDefault();
+        return;
+      }
+      if (modKey && e.key.toLowerCase() === "p") {
+        e.preventDefault();
+        return;
+      }
+    }
+    function handleContextMenu(e) {
+      e.preventDefault();
+    }
+    document.addEventListener("fullscreenchange", handleFullscreenChange);
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+    window.addEventListener("blur", handleBlur);
+    document.addEventListener("paste", handlePaste);
+    document.addEventListener("copy", handleCopy);
+    document.addEventListener("cut", handleCut);
+    document.addEventListener("dragstart", handleDragStart);
+    document.addEventListener("dragend", handleDragEnd);
+    document.addEventListener("drop", handleDrop);
+    document.addEventListener("dragover", handleDragOver);
+    document.addEventListener("keydown", handleKeydown);
+    document.addEventListener("contextmenu", handleContextMenu);
+    return () => {
+      document.removeEventListener("fullscreenchange", handleFullscreenChange);
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+      window.removeEventListener("blur", handleBlur);
+      document.removeEventListener("paste", handlePaste);
+      document.removeEventListener("copy", handleCopy);
+      document.removeEventListener("cut", handleCut);
+      document.removeEventListener("dragstart", handleDragStart);
+      document.removeEventListener("dragend", handleDragEnd);
+      document.removeEventListener("drop", handleDrop);
+      document.removeEventListener("dragover", handleDragOver);
+      document.removeEventListener("keydown", handleKeydown);
+      document.removeEventListener("contextmenu", handleContextMenu);
+    };
+  }, [enabled, addViolation, startCountdown, clearCountdown]);
+  return {
+    isFullscreen,
+    isMobileDevice,
+    violations,
+    warning,
+    fullscreenCountdown,
+    strikesRemaining,
+    hasEnteredFullscreen,
+    enterFullscreen
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  INSTANT_SUBMIT_VIOLATIONS,
+  useLockdown
+});

package/dist/index.mjs

@@ -0,0 +1,282 @@
+// src/useLockdown.ts
+import { useCallback, useEffect, useRef, useState } from "react";
+
+// src/types.ts
+var INSTANT_SUBMIT_VIOLATIONS = /* @__PURE__ */ new Set([
+  "paste_attempt",
+  "copy_attempt",
+  "cut_attempt",
+  "drop_attempt",
+  "devtools_attempt"
+]);
+
+// src/useLockdown.ts
+var DEFAULT_GRACE_PERIOD_MS = 5e3;
+var WARNING_DISPLAY_MS = 5e3;
+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;
+function detectMobileDevice() {
+  if (typeof navigator === "undefined") return false;
+  const hasTouch = navigator.maxTouchPoints > 0;
+  const isSmallScreen = window.screen.width < 1024;
+  const mobileUA = /Android|iPhone|iPad|iPod|webOS|BlackBerry|Opera Mini|IEMobile/i.test(
+    navigator.userAgent
+  );
+  return mobileUA || hasTouch && isSmallScreen;
+}
+function useLockdown({
+  enabled,
+  gracePeriodMs = DEFAULT_GRACE_PERIOD_MS,
+  onAutoSubmit,
+  onViolation
+}) {
+  const [isFullscreen, setIsFullscreen] = useState(false);
+  const [violations, setViolations] = useState([]);
+  const [warning, setWarning] = useState(null);
+  const [isMobileDevice] = useState(() => detectMobileDevice());
+  const [fullscreenCountdown, setFullscreenCountdown] = useState(
+    null
+  );
+  const [strikesRemaining, setStrikesRemaining] = useState(MAX_FULLSCREEN_EXITS);
+  const [hasEnteredFullscreen, setHasEnteredFullscreen] = useState(false);
+  const graceRef = useRef(false);
+  const fullscreenExitCountRef = useRef(0);
+  const lastFsExitRef = useRef(0);
+  const countdownIntervalRef = useRef(
+    null
+  );
+  const countdownStartRef = useRef(0);
+  const autoSubmittedRef = useRef(false);
+  const internalDragRef = useRef(false);
+  const hasEnteredFullscreenRef = useRef(false);
+  const onAutoSubmitRef = useRef(onAutoSubmit);
+  useEffect(() => {
+    onAutoSubmitRef.current = onAutoSubmit;
+  }, [onAutoSubmit]);
+  const onViolationRef = useRef(onViolation);
+  useEffect(() => {
+    onViolationRef.current = onViolation;
+  }, [onViolation]);
+  const triggerAutoSubmit = useCallback(() => {
+    if (autoSubmittedRef.current) return;
+    autoSubmittedRef.current = true;
+    onAutoSubmitRef.current();
+  }, []);
+  const clearCountdown = useCallback(() => {
+    if (countdownIntervalRef.current) {
+      clearInterval(countdownIntervalRef.current);
+      countdownIntervalRef.current = null;
+    }
+    countdownStartRef.current = 0;
+    setFullscreenCountdown(null);
+  }, []);
+  const startCountdown = useCallback(() => {
+    clearCountdown();
+    countdownStartRef.current = Date.now();
+    setFullscreenCountdown(FULLSCREEN_REENTRY_SECONDS);
+    countdownIntervalRef.current = setInterval(() => {
+      const elapsed = (Date.now() - countdownStartRef.current) / 1e3;
+      const remaining = Math.max(
+        0,
+        Math.ceil(FULLSCREEN_REENTRY_SECONDS - elapsed)
+      );
+      setFullscreenCountdown(remaining);
+      if (remaining <= 0) {
+        clearCountdown();
+        triggerAutoSubmit();
+      }
+    }, 500);
+  }, [clearCountdown, triggerAutoSubmit]);
+  useEffect(() => {
+    return () => clearCountdown();
+  }, [clearCountdown]);
+  const addViolation = useCallback(
+    (type) => {
+      if (graceRef.current) return;
+      if (!hasEnteredFullscreenRef.current) return;
+      if (autoSubmittedRef.current) return;
+      const v = { type, timestamp: Date.now() };
+      setViolations((prev) => [...prev, v]);
+      onViolationRef.current?.(v);
+      if (INSTANT_SUBMIT_VIOLATIONS.has(type)) {
+        setWarning("Your work has been submitted.");
+        triggerAutoSubmit();
+        return;
+      }
+      if (type === "fullscreen_exit") {
+        fullscreenExitCountRef.current += 1;
+        const remaining = MAX_FULLSCREEN_EXITS - fullscreenExitCountRef.current;
+        setStrikesRemaining(remaining);
+        if (remaining < 0) {
+          setWarning("Your work has been submitted.");
+          triggerAutoSubmit();
+        } else if (remaining === 0) {
+          setWarning(
+            "Final warning: leave fullscreen again and your work will be auto-submitted."
+          );
+          setTimeout(() => setWarning(null), WARNING_DISPLAY_MS);
+        } else {
+          setWarning(
+            `Warning: you have ${remaining} chance${remaining > 1 ? "s" : ""} left to re-enter fullscreen.`
+          );
+          setTimeout(() => setWarning(null), WARNING_DISPLAY_MS);
+        }
+      }
+    },
+    [triggerAutoSubmit]
+  );
+  const enterFullscreen = useCallback(async () => {
+    try {
+      await document.documentElement.requestFullscreen();
+      setIsFullscreen(true);
+      clearCountdown();
+      if (!hasEnteredFullscreenRef.current) {
+        hasEnteredFullscreenRef.current = true;
+        setHasEnteredFullscreen(true);
+        graceRef.current = true;
+        setTimeout(() => {
+          graceRef.current = false;
+        }, gracePeriodMs);
+      } else {
+        setHasEnteredFullscreen(true);
+      }
+    } catch {
+      if (hasEnteredFullscreenRef.current) {
+        startCountdown();
+      }
+    }
+  }, [gracePeriodMs, clearCountdown, startCountdown]);
+  useEffect(() => {
+    if (!enabled) return;
+    function handleBeforeUnload(e) {
+      e.preventDefault();
+    }
+    window.addEventListener("beforeunload", handleBeforeUnload);
+    return () => window.removeEventListener("beforeunload", handleBeforeUnload);
+  }, [enabled]);
+  useEffect(() => {
+    if (!enabled) return;
+    function handleFullscreenChange() {
+      const fs = !!document.fullscreenElement;
+      setIsFullscreen(fs);
+      if (fs) {
+        hasEnteredFullscreenRef.current = true;
+        setHasEnteredFullscreen(true);
+        clearCountdown();
+      } else if (!graceRef.current && hasEnteredFullscreenRef.current) {
+        lastFsExitRef.current = Date.now();
+        addViolation("fullscreen_exit");
+        if (fullscreenExitCountRef.current <= MAX_FULLSCREEN_EXITS) {
+          startCountdown();
+        }
+      }
+    }
+    function handleVisibilityChange() {
+      if (document.hidden && !graceRef.current && !countdownIntervalRef.current) {
+        addViolation("tab_switch");
+      }
+    }
+    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");
+    }
+    function handlePaste(e) {
+      e.preventDefault();
+      addViolation("paste_attempt");
+    }
+    function handleCopy(e) {
+      e.preventDefault();
+      addViolation("copy_attempt");
+    }
+    function handleCut(e) {
+      e.preventDefault();
+      addViolation("cut_attempt");
+    }
+    function handleDragStart() {
+      internalDragRef.current = true;
+    }
+    function handleDragEnd() {
+      internalDragRef.current = false;
+    }
+    function handleDrop(e) {
+      if (internalDragRef.current) {
+        internalDragRef.current = false;
+        return;
+      }
+      e.preventDefault();
+      addViolation("drop_attempt");
+    }
+    function handleDragOver(e) {
+      e.preventDefault();
+    }
+    function handleKeydown(e) {
+      const modKey = e.ctrlKey || e.metaKey;
+      if (e.key === "F12") {
+        e.preventDefault();
+        addViolation("devtools_attempt");
+        return;
+      }
+      if (modKey && e.shiftKey && DEVTOOLS_KEYS.includes(e.key.toUpperCase())) {
+        e.preventDefault();
+        addViolation("devtools_attempt");
+        return;
+      }
+      if (modKey && e.key.toLowerCase() === "u") {
+        e.preventDefault();
+        return;
+      }
+      if (modKey && e.key.toLowerCase() === "p") {
+        e.preventDefault();
+        return;
+      }
+    }
+    function handleContextMenu(e) {
+      e.preventDefault();
+    }
+    document.addEventListener("fullscreenchange", handleFullscreenChange);
+    document.addEventListener("visibilitychange", handleVisibilityChange);
+    window.addEventListener("blur", handleBlur);
+    document.addEventListener("paste", handlePaste);
+    document.addEventListener("copy", handleCopy);
+    document.addEventListener("cut", handleCut);
+    document.addEventListener("dragstart", handleDragStart);
+    document.addEventListener("dragend", handleDragEnd);
+    document.addEventListener("drop", handleDrop);
+    document.addEventListener("dragover", handleDragOver);
+    document.addEventListener("keydown", handleKeydown);
+    document.addEventListener("contextmenu", handleContextMenu);
+    return () => {
+      document.removeEventListener("fullscreenchange", handleFullscreenChange);
+      document.removeEventListener("visibilitychange", handleVisibilityChange);
+      window.removeEventListener("blur", handleBlur);
+      document.removeEventListener("paste", handlePaste);
+      document.removeEventListener("copy", handleCopy);
+      document.removeEventListener("cut", handleCut);
+      document.removeEventListener("dragstart", handleDragStart);
+      document.removeEventListener("dragend", handleDragEnd);
+      document.removeEventListener("drop", handleDrop);
+      document.removeEventListener("dragover", handleDragOver);
+      document.removeEventListener("keydown", handleKeydown);
+      document.removeEventListener("contextmenu", handleContextMenu);
+    };
+  }, [enabled, addViolation, startCountdown, clearCountdown]);
+  return {
+    isFullscreen,
+    isMobileDevice,
+    violations,
+    warning,
+    fullscreenCountdown,
+    strikesRemaining,
+    hasEnteredFullscreen,
+    enterFullscreen
+  };
+}
+export {
+  INSTANT_SUBMIT_VIOLATIONS,
+  useLockdown
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@rcnr/lockdown",
+  "version": "1.0.0",
+  "description": "Shared fullscreen lockdown hook for RCNR student frontends",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0"
+  },
+  "keywords": [
+    "rcnr",
+    "lockdown",
+    "fullscreen",
+    "react",
+    "hook"
+  ],
+  "author": "Ryan-RCNR",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Ryan-RCNR/rcnr-lockdown.git"
+  }
+}