@minicode-dev/chat 0.1.10 → 0.1.12

package/README.md

@@ -211,6 +211,22 @@ it is responsible for upload permissions, storage and preserving images used in
 The local demo includes a session-only image uploader (PNG/JPG/WebP/GIF, up to 256 KB
 and 2048 × 2048) and an example image. Open **Nuevas funciones** to try it.
 
+## Countdown messages
+
+Open **✨ → Cuenta regresiva**, choose a quick duration button or a custom duration in seconds or minutes
+(up to 24 hours), select the final effect (pig, confetti or nudge), and choose
+whether to include its sound. **Probar efecto** previews the selection without sending.
+Send it to display a live countdown in the conversation. The card hides the chosen
+effect until zero; quotes and conversation previews also keep the surprise.
+The last ten seconds animate; at zero, the visible conversation plays the selected
+effect, respecting automatic playback, sound preferences and reduced motion.
+
+Countdowns use ordinary text messages with a separate `[minicode-countdown:v1]`
+payload containing an absolute deadline. No backend change is needed. Both clients
+need this library version for the countdown UI; older clients show readable fallback
+text. Device clocks should be accurate. Closed or hidden conversations do not play
+the deadline effect; expired cards offer manual replay on return.
+
 ## Zumbidos and animated effects
 
 The chat includes a nudge, a dancing pig and confetti with approved audio recordings.
@@ -321,3 +337,96 @@ Use WASD/arrows, mouse and click/space on desktop, or the joystick, arena touch
 button on mobile. Minimize preserves the match; reload/reopening the chat is not a persisted
 match recovery flow. Wi-Fi versus cellular connectivity and runtime TURN still require real-device
 validation.
+
+### Manual TURN recovery inside TANQUES LIVE
+
+Both players need a version with manual TURN support. No Django endpoint, consumer,
+WebSocket protocol change, Cloudflare SDK, or application-level screen is required.
+The existing `webrtc.iceServers` and `iceTransportPolicy` provider settings continue
+working. Manual settings belong only to the current match and are not persisted.
+
+1. Invite the other player and accept the match normally. Local/direct connections
+   keep working without TURN.
+2. During negotiation (or even during a connected match), choose **Configurar
+   conexión alternativa**. A slow or failed negotiation also shows a connection notice.
+3. **One player** pastes the JSON containing temporary `iceServers` and selects
+   **Aplicar y reconectar**. The other player receives and applies it automatically;
+   they do not need to paste anything.
+4. Wait for the sharing confirmation, then inspect the actual connection state.
+   Applied credentials do not by themselves prove that TURN is reachable or in use.
+
+The modal accepts `{ "iceServers": [...] }` and a full Cloudflare envelope such as
+`{ "success": true, "result": { "iceServers": [...] } }`. It rejects invalid JSON,
+STUN-only configurations, invalid ICE URLs, missing TURN passwords, known expired
+credentials, and API-token fields. Limits: 6,000 characters/UTF-8 bytes, eight ICE
+servers and sixteen URLs. Only `stun:`, `stuns:`, `turn:` and `turns:` URLs are allowed.
+
+**Never paste the permanent Cloudflare TURN API token.** Generate temporary
+credentials externally in your terminal. For example, with your credentials already
+set in your terminal environment (not in React), this copies only the temporary
+response to the macOS clipboard:
+
+```sh
+curl --fail --silent --show-error \
+  "https://rtc.live.cloudflare.com/v1/turn/keys/${CLOUDFLARE_TURN_KEY_ID}/credentials/generate-ice-servers" \
+  --header "Authorization: Bearer ${CLOUDFLARE_TURN_KEY_API_TOKEN}" \
+  --header "Content-Type: application/json" \
+  --data '{"ttl":3600}' | pbcopy
+```
+
+The library never calls that API. The optional **Validez restante en segundos** field
+means remaining validity from now, not the original issuance TTL. Leave it blank
+when unknown; Cloudflare's opaque username is not treated as an expiry timestamp.
+You can also supply `expiresAt` (ISO text or Unix milliseconds) or `expiresIn`/`ttl`
+(remaining seconds) in the JSON. Known-expired settings are refused; expiry unknown
+cannot be detected reliably from every ICE authentication failure, so obtain and
+paste new credentials if the old ones stop working.
+
+Recovery uses the private chat signaling already used for SDP/ICE. A tab-bound,
+ephemeral ECDH/AES-GCM exchange encrypts the credentials before they enter the chat
+transport. The host coordinates preparation, confirmation and recovery so either
+player can initiate without racing two restart offers. A healthy direct connection
+with policy `all` is kept; new fallback settings do not trigger an unnecessary
+restart. Otherwise the link updates `setConfiguration()` and restarts ICE, or
+recreates only PeerConnections when necessary. Positions, health and match state
+remain in the existing simulation. Drafts clear on closing/applying the dialog;
+credentials and encryption keys clear when the match ends or is destroyed.
+
+The library excludes these internal frames from its visible client history and
+unread counts; any server that stores all chat frames may still retain encrypted
+signaling. No plaintext TURN password is sent in those frames. This relies on the
+existing authenticated private-room relay; it is not protection against an actively
+malicious signaling server. HTTPS (or localhost) and Web Crypto are required. Without
+Web Crypto, sharing fails safely instead of sending plaintext. Closing the dialog
+does not end the match; an already-started synchronization can still finish.
+
+**Diagnostics and real-network validation:**
+
+- Open **Diagnóstico de conexión** to see SDP/ICE/gathering states, DataChannel
+  readiness, reconnects, connection time, RTT and sanitized ICE errors/counters.
+- `turnConfigured` only means a TURN URL is configured. `candidates.localRelay`
+  means relay candidates were gathered. `selectedPair.relay: true` means the actual
+  selected candidate pair uses TURN. No passwords, usernames, SDP or private candidate
+  addresses are included in the panel.
+- To verify TURN, temporarily enable **Forzar relay para diagnóstico**. It is shared
+  with the settings so both peers use `iceTransportPolicy: "relay"`. Confirm both
+  DataChannels are open, `phase` is `connected`, the selected pair is relay, and
+  movement counters increase on both devices. Disable the option for normal play.
+- Test from two devices on different networks (for example Wi-Fi and cellular),
+  with current temporary credentials. Also test interruption/retry and renewing
+  credentials from either player. No implementation can guarantee connectivity
+  through every restrictive firewall; TURN/TLS over TCP may add latency/jitter.
+- The local two-player demo remains `/tanks-live-lab.html?user=ana` and
+  `/tanks-live-lab.html?user=luis`. Automated tests use fake RTC/TURN to verify
+  synchronization, retries, privacy and state preservation; they do not prove that
+  a real TURN service is reachable across networks.
+
+For repeatable browser QA, `scripts/check-manual-turn-browser.mjs` uses Playwright
+as an optional development tool (not a library dependency). Run the demo, make a
+Playwright installation available, then run the script. `CHAT_DEMO_URL` overrides
+the default `http://127.0.0.1:5173`; `PLAYWRIGHT_MODULE` and
+`PLAYWRIGHT_EXECUTABLE_PATH` can select an existing tooling installation. It checks
+two real local browser peers, host/guest manual sharing with dummy credentials,
+invalid inputs, light/dark/mobile dialogs, cancellation and simulated blocked ICE.
+Its headless-only flags allow local candidates without mDNS resolution. The script
+never tests real TURN credentials or proves Wi-Fi/cellular connectivity.