fix: sector event routing, type guards, and color field (#99)

* fix: pass side field through sector events to extension

- fnc_trackSectors: include str _newOwner (side) in captured events,
  empty string for contested events
- fnc_handleCustomEvent: extract side string from eventMessage[2]
  and pass it as a typed positional arg to :EVENT:SECTOR:

* docs: design for separating capturedFlag from :EVENT:SECTOR:

* fix: remove capturedFlag from :EVENT:SECTOR: routing

capturedFlag has player-centric fields (unitName, unitSide, flagSide)
incompatible with sector-centric fields (objectType, unitName, side,
position). Let it fall through to :EVENT:GENERAL: instead.

* fix: simplify side extraction in sector event routing

param [2, ""] already guarantees a string default, so the isEqualType
check was redundant.

* fix: add type guard for side extraction in sector events

param [2, ""] returns the raw value at index 2 even if it's an array
(position), not the default. Use param's type-check argument [2, "", [""]]
to ensure only strings are accepted as side, falling back to "" for
non-string values like position arrays at index 2.

* fix: update sector event comment and add type guards to all params

Document the full format [objectType, unitName, side, color, position]
and note that color is not captured by the extension. Add type guards
to params 0 and 1 for consistency.

* feat: capture color field from sector events

Extract color (index 3) from the event message array and send it to
the extension as part of the :EVENT:SECTOR: args. Format changes from
[frame, type, objectType, unitName, side, posX?, posY?, posZ?] to
[frame, type, objectType, unitName, side, color, posX?, posY?, posZ?].

* fix: restore sector example in comment, not flag capture

* fix: add empty color field to sector capture events

fnc_trackSectors sends [objectType, name, side, position] but the
extension now expects color between side and position. Add empty string
for color since sectors don't have a meaningful color value.

* chore: remove outdated design doc

Author: fank

addons/recorder/fnc_handleCustomEvent.sqf

@@ -5,9 +5,10 @@
 
   Description:
     Routes custom events to the extension with typed positional args based on
-    event type. Sector events (captured/contested/capturedFlag) use :EVENT:SECTOR:
-    with structured fields; endMission uses :EVENT:ENDMISSION: with side and
-    message; all other events use :EVENT:GENERAL: with JSON-encoded extraData.
+    event type. Sector events (captured/contested) use :EVENT:SECTOR: with
+    structured fields; endMission uses :EVENT:ENDMISSION: with side and
+    message; all other events (including capturedFlag) use :EVENT:GENERAL:
+    with JSON-encoded extraData.
 
     Applied during initialization of OCAP in <OCAP_recorder_fnc_init>.
 
@@ -22,7 +23,7 @@
   Examples:
     (start code)
     // Sector captured with structured data (sent by fnc_trackSectors)
-    [QGVARMAIN(customEvent), ["captured", ["sector", "Sector Alpha", [100, 200, 0]]]] call CBA_fnc_localEvent;
+    [QGVARMAIN(customEvent), ["captured", ["sector", "Sector Alpha", str west, "", getPos _sector]]] call CBA_fnc_localEvent;
 
     // End mission with side and message
     [QGVARMAIN(customEvent), ["endMission", [str west, "BLUFOR controlled all sectors!"]]] call CBA_fnc_localEvent;
@@ -49,14 +50,15 @@ params [
 
 switch (_eventName) do {
   case "captured";
-  case "contested";
-  case "capturedFlag": {
+  case "contested": {
     private _args = [GVAR(captureFrameNo), _eventName];
 
     if (_eventMessage isEqualType []) then {
-      // Array format: ["objectType", "unitName", ...maybePosition...]
-      _args pushBack (_eventMessage param [0, ""]);
-      _args pushBack (_eventMessage param [1, ""]);
+      // Array format: [objectType, unitName, side, color, [posX, posY, posZ]]
+      _args pushBack (_eventMessage param [0, "", [""]]);
+      _args pushBack (_eventMessage param [1, "", [""]]);
+      _args pushBack (_eventMessage param [2, "", [""]]);
+      _args pushBack (_eventMessage param [3, "", [""]]);
       {
         if (_x isEqualType [] && {count _x >= 2} && {(_x # 0) isEqualType 0}) exitWith {
           _args append _x;

addons/recorder/fnc_trackSectors.sqf

@@ -41,9 +41,9 @@ if (_this isEqualType [] && {count _this > 0}) exitWith {
 
     private _pos = getPosATL _sector;
     if (_newOwner isEqualTo sideUnknown) then {
-      [QGVARMAIN(customEvent), ["contested", ["sector", _name, _pos]]] call CBA_fnc_localEvent;
+      [QGVARMAIN(customEvent), ["contested", ["sector", _name, "", "", _pos]]] call CBA_fnc_localEvent;
     } else {
-      [QGVARMAIN(customEvent), ["captured", ["sector", _name, _pos]]] call CBA_fnc_localEvent;
+      [QGVARMAIN(customEvent), ["captured", ["sector", _name, str _newOwner, "", _pos]]] call CBA_fnc_localEvent;
     };
   }] call BIS_fnc_addScriptedEventHandler;
 };