feat: Add FaceAI integration with handoff and return functionality

- Introduced a new workspace for FaceAI in package.json.
- Implemented FaceAI handoff logic in faceai_handoff.php, including identity verification and token signing.
- Created faceai_return.php to handle return requests from FaceAI, validating tokens and forwarding results.
- Developed faceai_simulator.php and faceai_simulator_view.php for simulating the FaceAI interface with demo photos.
- Enhanced rus-ecom-240621.js to support new FaceAI features, including dynamic URL building and button integration.
- Added faceai_config.php for configuration management, including environment variable handling and utility functions.
- Updated HTML structure and styles in simulator view for better user experience.

www/faceai_handoff.php

@@ -0,0 +1,76 @@
+<?php
+
+require_once __DIR__ . '/faceai_config.php';
+
+$config = faceai_config();
+
+try {
+    $raceId = faceai_request_value('raceId');
+    $raceSlug = faceai_request_value('raceSlug');
+    $raceName = faceai_request_value('raceName', $raceSlug !== '' ? $raceSlug : $raceId);
+    $lang = faceai_request_value('lang', 'it');
+    $returnUrl = faceai_request_value('returnUrl');
+
+    if ($raceId === '' || $returnUrl === '') {
+        faceai_render_message_page(
+            'FaceAI handoff non disponibile',
+            'Mancano i parametri minimi richiesti per lanciare FaceAI.',
+            array(
+                'Parametri richiesti: raceId, returnUrl.',
+                'Il pulsante Face ID deve passare anche raceSlug e lang quando disponibili.'
+            ),
+            400
+        );
+    }
+
+    $identity = faceai_resolve_identity($config);
+    if ($identity === null) {
+        faceai_render_message_page(
+            'FaceAI handoff in attesa del bridge legacy',
+            'Questo endpoint PHP non puo leggere la sessione Java esistente. Per funzionare in produzione deve ricevere una identita firmata dal layer legacy o dal reverse proxy.',
+            array(
+                'Opzione consigliata: cookie firmato ' . $config['identity_cookie'] . ' con payload type=legacy-identity.',
+                'Per test locale e possibile passare devUserId, devDisplayName, devEmail e devMembershipStatus se FACEAI_ALLOW_DEV_HANDOFF=1.',
+                'Esempio locale: faceai_handoff.php?raceId=101&raceSlug=mezza-di-firenze&lang=it&returnUrl=http%3A%2F%2Flocalhost%2Fold&devUserId=1&devDisplayName=Mario%20Rossi&devEmail=mario%40example.test&devMembershipStatus=active'
+            ),
+            501
+        );
+    }
+
+    if (($identity['membershipStatus'] ?? 'inactive') !== 'active') {
+        faceai_render_message_page(
+            'FaceAI non disponibile',
+            'L utente corrente non risulta abilitato all uso di FaceAI in base allo stato di membership.',
+            array('Stato attuale: ' . ($identity['membershipStatus'] ?? 'unknown')),
+            403
+        );
+    }
+
+    $payload = array(
+        'type' => 'handoff',
+        'user' => array(
+            'id' => $identity['id'],
+            'displayName' => $identity['displayName'],
+            'email' => $identity['email'],
+            'membershipStatus' => $identity['membershipStatus']
+        ),
+        'race' => array(
+            'id' => $raceId,
+            'slug' => $raceSlug !== '' ? $raceSlug : $raceId,
+            'name' => $raceName !== '' ? $raceName : $raceId
+        ),
+        'lang' => $lang,
+        'returnUrl' => $returnUrl,
+        'expiresAt' => ((int) round(microtime(true) * 1000)) + (5 * 60 * 1000)
+    );
+
+    $token = faceai_sign_payload($payload, $config['shared_secret']);
+    $targetUrl = faceai_build_url($config['frontend_url'] . '/auth/callback', array('token' => $token));
+
+    header('Cache-Control: no-store, no-cache, must-revalidate, max-age=0');
+    header('Pragma: no-cache');
+    header('Location: ' . $targetUrl, true, 302);
+    exit;
+} catch (Throwable $error) {
+    faceai_render_message_page('Errore handoff FaceAI', $error->getMessage(), array(), 500);
+}