Session-Sniffer — Copilot Instructions

Session Sniffer is a Windows‑only (PyQt6) packet sniffer focused on P2P game sessions. The entry point is src/session_sniffer/main.py (module execution via python -m session_sniffer), which orchestrates: environment checks, settings load, interface discovery, packet capture startup, background processing threads, and GUI initialization. Core logic lives under src/session_sniffer/ in cohesive subpackages (capture, guis, networking, rendering_core, models, constants, discord). Data flows from live packet capture → player/session registries → rendering core → GUI worker thread signal → Qt table models/views. Important import note: even with the src/ layout, Python imports remain from session_sniffer..., not from src.session_sniffer.... The src directory is a source root on PYTHONPATH; it is not part of the package name.

• Adding a new player column: Append to Settings.GUI_ALL_CONNECTED_COLUMNS, add to GUI_TOGGLEABLE_CONNECTED_COLUMNS and/or GUI_TOGGLEABLE_DISCONNECTED_COLUMNS, update rendering_core mapping, and refresh header texts. • Adding a resource directory: Place under repo root, then append to datas in Session_Sniffer.spec with correct relative path mapping. • Adding a detection toggle: Create a flag in GUIDetectionSettings, add QAction in the Detection menu mirroring existing pattern, and integrate logic where warnings are issued.

This project never maintains backward compatibility. When renaming, removing, or replacing anything (settings keys, field names, constants, APIs, file paths), always: • Delete the old name/code outright. • Update every call site to use the new name. • Never add migration shims, alias wrappers, fallback lookups, or transitional validators. • Never add code whose sole purpose is to handle the old form "just in case" users have old data. If a user's saved data (e.g. Settings.ini) contains a stale key, it is treated as unknown and discarded by the existing rewrite logic — that is intentional and acceptable.

• Packet Capture: PacketCapture is constructed from an immutable CaptureConfig (see src/session_sniffer/capture/packet_capture.py) and invokes config.callback (created in src/session_sniffer/main.py) for each packet. That callback updates PlayersRegistry, detection warnings, and may spawn user IP processing threads. • PacketCapture config/state: Read config via capture.config (e.g., capture.config.interface). Runtime state (threads/events/process handles) lives in an internal _CaptureState dataclass. • Player State: Connected/disconnected movement handled via registry methods and Player.left_event. Rejoins call mark_as_rejoined; periodic packets call mark_as_seen. • Rendering: Background thread rendering_core compiles GUIUpdatePayload objects using GUIrenderingData and emits them via GUIWorkerThread.update_signal. Avoid direct GUI mutations from non‑GUI threads. • GUI: MainWindow owns two SessionTableView / SessionTableModel pairs (connected & disconnected). Heavy operations are skipped when a table is hidden; selection counts update headers. Respect existing optimization checks (connected_count_changed, visibility guards). • Settings: Loaded frequently from Settings.ini via Settings.load_from_settings_file; after in‑memory changes call Settings.reconstruct_settings(). Feature toggles (detection flags, interface overrides) rely on this persistence. • Screen Resolution: Always obtain via get_screen_size() which raises UnsupportedScreenResolutionError if below minimum; catch and display its msgbox_text. • Concurrency: Threads are created as daemon named logically (e.g., ProcessUserIPTask-<ip>-connected). Uncaught exceptions in threads are handled automatically via threading.excepthook (installed in src/session_sniffer/core/control.py).