@minicode-dev/chat 0.1.12 → 0.1.14

package/README.md

@@ -1,59 +1,86 @@
 # @minicode-dev/chat
 
-Real-time chat for React (WebSocket, reactions, editing, emoji, GIFs/stickers via KLIPY, file and voice
-attachments, notifications, Connect 4 and 3D Battleship).
+Real-time chat for React: WebSocket transport, reactions, editing, replies, emoji, GIFs/stickers via KLIPY,
+file and voice attachments, YouTube players, notifications, animated effects and four two-player games.
 
-Standalone, reusable npm package for integration into React applications through configurable
-providers and transport adapters.
+A standalone, reusable npm package. The host application supplies the transport, authentication and served
+assets through configuration; nothing is tied to a specific backend or application.
 
-- Owner: **Minicode** · License: `UNLICENSED`.
+- Owner: **Minicode** · License: `UNLICENSED` · Public on npm (`publishConfig.access: public`).
+- The UI copy is in Spanish.
 
-## Installation
+## Features
 
-Install the package from npm. If your registry requires authentication, configure an `.npmrc` in
-the host project (keep the token out of git, e.g. via an environment variable):
+| Feature | What you get | Host requirements |
+|---|---|---|
+| Messaging | Private chats and groups, replies, editing, reactions, presence, user search, unread badges | WebSocket backend speaking the chat protocol (see [Wire protocol](#wire-protocol)) |
+| Emoji | Unicode picker (English/Spanish search, recents, favorites, skin tones), `:shortcode` autocomplete, emoticons such as `:)` and `<3` | Bundler with JSON `import()` support |
+| Custom emoji | Image emojis per provider in messages, picker, autocomplete and reactions | `media.emoji.custom` catalog and image hosting |
+| GIFs and stickers | KLIPY search, categories, local favorites/recents | `configureKlipy({ apiKey })` and an attachment-capable `sendMessage` |
+| Attachments and voice notes | Files up to 10 MB, in-browser voice recording | Attachment-capable `sendMessage`; microphone permission |
+| YouTube | Inline player for the first supported link per message | CSP `frame-src https://www.youtube-nocookie.com` |
+| Effects | Zumbido, Cerdito disco, Confeti, Avalancha and countdown messages | Served sounds; optional `three` |
+| Games | Conecta 4, Batalla Naval 3D, Tanques de guerra (turn-based), Tanques LIVE 3D (WebRTC) | Games transport bridge; served sounds; optional `three` |
+| Notifications and PWA | Desktop notifications, app badge, message sounds, detached window, install prompt | `<ChatNotifications />` or the `start*` services; your own `/chat` route |
+| Theming | `light`, `dark`, `auto`, `black` | `theme` prop, or the host's `body.dark-mode` / `[data-theme]` |
 
-```ini
-@minicode-dev:registry=https://registry.npmjs.org/
-//registry.npmjs.org/:_authToken=${NPM_TOKEN}
-```
+## Installation
 
 ```bash
 npm install @minicode-dev/chat react react-dom zustand lucide-react
-# Only if Battleship 3D is enabled:
-npm install three@">=0.134.0 <0.138.0"
+# Optional, only for the 3D scenes (games and effects fall back without it):
+npm install "three@>=0.134.0 <0.138.0"
 ```
 
-### Peer dependencies
-
-| Package | Range | Notes |
+| Peer | Range | Notes |
 |---|---|---|
 | `react`, `react-dom` | `>=18` | |
 | `zustand` | `^4.5.0 \|\| ^5.0.0` | |
 | `lucide-react` | `>=0.400.0` | |
-| `three` | `>=0.134.0 <0.138.0` | Optional, only for Battleship 3D (loaded lazily). |
+| `three` | `>=0.134.0 <0.138.0` | Optional. Loaded with dynamic `import()` only when a 3D scene starts. |
+
+`dayjs` and `emojibase-data` are regular dependencies. The emoji catalog (~1.4 MB of JSON) is loaded with dynamic
+`import()` the first time it is needed, so the host bundler must support JSON imports (Vite, webpack 5,
+esbuild, Rollup with `@rollup/plugin-json`).
 
-`emojibase-data` and `dayjs` are regular dependencies. The emoji catalog (~1.4 MB of JSON) is loaded with
-dynamic `import()` the first time the composer/emoji picker mounts, so the host bundler must support
-JSON imports (Vite, webpack 5, Rollup with `@rollup/plugin-json`, esbuild do).
+The package is ESM only (`dist/index.js`). JavaScript does not import the stylesheet; import it yourself.
 
-## Usage
+## Quick start
 
 ```jsx
+import { useEffect } from 'react';
 import {
   LiraChatProvider, ChatButton, ChatWindow, ChatPage, ChatNotifications,
+  chatGamesStore, useChatTransport,
 } from '@minicode-dev/chat';
 import '@minicode-dev/chat/styles.css';
 
 const config = {
   websocket: { url: 'wss://chat.example.com/ws' },
   auth: { getToken: () => localStorage.getItem('token') },
-  callbacks: { onError: (error) => console.error(error) },
+  user: { id: 'user-123', name: 'Ana' },
+  callbacks: { onConnectionChange: (status) => console.info('chat', status) },
 };
 
+// Games travel as chat text: give the games store a way to send it.
+function ChatGamesBridge() {
+  const transport = useChatTransport();
+  useEffect(() => {
+    if (!transport) return undefined;
+    chatGamesStore.getState().configureTransport({
+      send: (roomId, text) => transport.request('CHAT_MESSAGE', { room_id: roomId, message: text }),
+      getScope: () => transport.getIdentity().scope,
+      getUserId: () => transport.getIdentity().userId,
+    });
+    return () => chatGamesStore.getState().configureTransport(null);
+  }, [transport]);
+  return null;
+}
+
 export function App() {
   return (
     <LiraChatProvider config={config}>
+      <ChatGamesBridge />
       <ChatButton label="Chat" />
       <ChatWindow placement="floating" />
       <ChatNotifications />
@@ -61,136 +88,162 @@ export function App() {
   );
 }
 
-// Full-page route (e.g. /chat, also used by the "detach" window):
+// Full-page route (default `/chat`), also opened by the "detach" button:
 export function ChatRoute() {
   return (
     <LiraChatProvider config={config}>
+      <ChatGamesBridge />
       <ChatPage />
     </LiraChatProvider>
   );
 }
 ```
 
-- `LiraChatProvider` props: `config`, `transport` (inject your own `ChatTransport` adapter;
-  the provider never closes an injected transport), `stores`, `chatStore` and `children`. Without a
-  `transport`, a standalone WebSocket transport is created from `config.websocket.url`.
-- `ChatWindow` props: `placement` (`'floating' | 'modal' | 'embedded'`), `open` / `onOpenChange`
-  (controlled mode), `className`, `BattleshipPreviewComponent`.
-- `ChatPage`: `className`. `ChatButton`: `className`, `label`. `ChatNotifications`: no props.
-- Lower level: `createStandaloneTransport`, `createChatStore`, hooks (`useChatConfig`, `useChatTransport`,
-  `useChatConnection`, `useChatUnreadTotal`) and presentational primitives (`ChatWindowShell`,
-  `MessageList`, `MessageComposer`, pickers…). See `index.d.ts` for the full typed API; anything not
-  exported from the package root is internal.
-
-## Styles
-
-Import the stylesheet once, anywhere in the host app:
-
-```js
-import '@minicode-dev/chat/styles.css';
-```
-
-## Assets (sounds)
+Then serve the sounds ([Assets](#assets-sounds)). Without the games bridge, game invitations fail with
+"Chat no disponible". The provider creates its transport and chat store once; remount it with a different
+`key` to change `websocket` or `auth`.
 
-Notification and game sounds ship in `assets/sounds/` (`ting.*`, `notification.*`, `connect4/*.ogg`,
-`battleship_audio_pack/assets/*.ogg`) but **the host serves them**. By default the chat requests them
-from `/sounds/...`. Either:
+## Host integration checklist
 
-1. Copy them into the host's public folder, e.g. in a `postinstall`/build step:
-
-   ```bash
-   mkdir -p public/sounds
-   cp -R node_modules/@minicode-dev/chat/assets/sounds/. public/sounds/
-   ```
-
-2. Or serve them from another path/CDN and point the chat at it, before any sound plays:
+1. **Styles:** `import '@minicode-dev/chat/styles.css'` once.
+2. **Sounds:** copy `assets/sounds/` to `/sounds/` or call `setChatAssetsBaseUrl()` ([Assets](#assets-sounds)).
+3. **Games:** call `chatGamesStore.getState().configureTransport({ send, getScope, getUserId })` (see Quick start).
+   Games only run in private rooms named `private_<userA>_<userB>`.
+4. **Attachments, GIFs, stickers and voice notes** are all sent as attachments. The default store sends text
+   only and rejects attachments ("Este transporte no admite adjuntos."). Create the store yourself with an
+   attachment-capable `sendMessage(roomId, message, attachments)` and pass it as `chatStore`:
 
    ```js
-   import { setChatAssetsBaseUrl } from '@minicode-dev/chat';
-   setChatAssetsBaseUrl('https://cdn.example.com/minicode-chat/sounds');
+   import { createChatStore } from '@minicode-dev/chat';
+   const chatStore = createChatStore({ transport, sendMessage: mySendMessage });
+   // <LiraChatProvider config={config} transport={transport} chatStore={chatStore}>
    ```
 
-   (`config.assets.baseUrl` exists in the config schema but is not wired yet; use the function.)
-
-The files are also exposed as `@minicode-dev/chat/assets/*` for bundlers that can import asset URLs.
+   Hosts that own a raw WebSocket can use the exported file relay: `sendRelayMessage(socket, roomId, message,
+   attachments)` sends files as 32 KB `CHAT_FILE` frames (one attachment per message, 1 byte to 10 MB);
+   `consumeRelayEvent(socket, frame)` and `hydrateRelayMessage(socket, message)` rebuild them on receipt;
+   `closeRelay(socket)` rejects pending sends. File bytes only live in connected browsers.
+5. **KLIPY:** `configureKlipy({ apiKey })` before the GIF/sticker pickers open ([GIFs](#gifs-and-stickers)).
+6. **Detached window / PWA:** render `<ChatPage />` at `/chat` (or set `pwa.path`). For the installable app,
+   call `startChatApp()` and `registerChatWorker({ path: '/chat', swUrl: '/chat-sw.js' })`; the service worker
+   file is yours, the package does not ship one.
+7. **Background services:** `<ChatNotifications />` starts desktop notifications, the app badge and message
+   and Connecta 4 sounds while mounted. Hosts can instead start `startDesktopNotifications()`,
+   `startAppBadge()` and `startConnect4Sounds()`. Cross-tab sync of unread counts, GIF library and emoji
+   preferences: `startUnreadStorageSync()`, `startGifLibrarySync()`, `startEmojiPreferencesSync()`. Every
+   starter returns `stop()`.
 
-## Local development
-
-This repository includes a local React demo that consumes the library source directly:
+## Assets (sounds)
 
-```bash
-npm install
-npm run dev
-```
+Sounds ship in the package under `assets/sounds/` (also exported as `@minicode-dev/chat/assets/*`), but **the
+host serves them**. By default the chat requests them from `/sounds/...`.
 
-Vite opens the chat in your browser. The demo provides simulated users, automatic replies,
-groups, emoji, reactions, message editing, attachments and a light/dark theme switch.
-Messages and uploaded files stay in memory and reset on reload. No login or WebSocket
-service is required. GIF/sticker search requires separately configured KLIPY credentials;
-multiplayer games are not simulated. Voice recording requires browser microphone permission.
-The `demo/` directory is excluded from the npm package by the `files` allowlist.
+| Path in `assets/sounds/` | Used by |
+|---|---|
+| `ting.mp3`/`.ogg`, `notification.mp3`/`.ogg` | New-message sounds |
+| `effects/nudge.mp3`, `cerdito_disco_original.mp3`, `confetti.mp3`, `avalanche.mp3` | Zumbido, Cerdito disco, Confeti, Avalancha |
+| `connect4/*.ogg` (8 files) | Conecta 4 |
+| `battleship_audio_pack/assets/*.ogg` (14 files) | Batalla Naval |
+| `tanks/*.mp3` and `tanks/*.ogg` (12 sounds, both formats) | Tanques de guerra and Tanques LIVE |
 
-To build or pack the library:
+Option 1, copy the folder into the host's public directory (Vite/CRA `public/` is served at `/`):
 
 ```bash
-npm install
-npm run build  # ESM library and styles in dist/
-npm pack       # builds again via prepack and creates an installable .tgz
+mkdir -p public/sounds
+cp -R node_modules/@minicode-dev/chat/assets/sounds/. public/sounds/
 ```
 
-To test local changes, install the generated tarball in a React application:
+Automate it so new sounds arrive with every package update. A cross-platform script (Node 16.7+):
 
-```bash
-# Run inside your consuming application; adjust the path and package version.
-npm install /path/to/minicode-chat/minicode-dev-chat-0.1.0.tgz
-npm run dev # if your application provides this script
+```js
+// scripts/copy-chat-sounds.mjs
+import { cpSync, mkdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+const packageDir = dirname(require.resolve('@minicode-dev/chat/package.json'));
+const target = join(process.cwd(), 'public', 'sounds');
+
+mkdirSync(target, { recursive: true });
+cpSync(join(packageDir, 'assets', 'sounds'), target, { recursive: true });
+console.log(`@minicode-dev/chat sounds copied to ${target}`);
 ```
 
-Repeat packing and installation after changes. Installation updates the consuming application's
-local dependency files. Real-time messaging requires a compatible WebSocket service and any
-necessary authentication, supplied by the consuming application.
-
-For source-based development, the custom `@minicode-dev/source` export condition points at `src/`.
-Tooling must explicitly enable it (for example through Vite's `resolve.conditions`) and resolve
-this local package. It is not enabled by default; React and other shared peers must resolve to
-one copy in the consuming application.
-
-## Publishing updates
+```json
+{
+  "scripts": {
+    "copy:chat-sounds": "node scripts/copy-chat-sounds.mjs",
+    "predev": "npm run copy:chat-sounds",
+    "prebuild": "npm run copy:chat-sounds"
+  }
+}
+```
 
-Log in yourself with `npm login`, then run:
+Option 2, serve them from another path or CDN and point the chat there before any sound plays:
 
-```bash
-npm run release                 # patch version, build, validate contents, publish
-npm run release -- minor        # minor version
-npm run release -- major        # major version
-npm run release -- --dry-run    # build and inspect; no version change or publication
+```js
+import { setChatAssetsBaseUrl } from '@minicode-dev/chat';
+setChatAssetsBaseUrl('https://cdn.example.com/minicode-chat/sounds');
 ```
 
-The release script checks your npm session, builds, increments the version without
-creating a Git commit or tag, and validates the exact archive before publishing it.
-Only `dist/`, `assets/`, public types, README, changelog and package metadata are allowed.
-Temporary archives and this package's root `.tgz` files are removed even on failure.
-Build output in `dist/` is retained for local use. If publication fails after the
-version bump, the updated version remains in `package.json` and the lockfile.
-Registry access follows `publishConfig` in `package.json`; login and any required
-npm authentication challenge are handled by you. No Git push is performed.
+`setChatAssetsBaseUrl(null)` restores `/sounds`. `config.assets.baseUrl` exists in the schema but is not wired;
+use the function. Missing files only silence the sound; visuals and games keep working.
 
-The command is named `release` because npm reserves `publish` as a lifecycle hook;
-a script with that name that calls `npm publish` could invoke itself recursively.
+## Components and API
 
-## Feature implementation notes
+| Export | Notes |
+|---|---|
+| `LiraChatProvider` | Props: `config`, `transport` (your own `ChatTransport`; never connected or closed by the provider), `stores`, `chatStore`, `children`. Without `transport`, a standalone WebSocket transport is created from `config.websocket.url`. |
+| `ChatWindow` | `placement`: `'floating'` (portal; minimize, maximize, detach; Escape minimizes), `'modal'` (backdrop and focus trap) or `'embedded'` (inline, always open). Also `open`/`onOpenChange` (controlled), `theme`, `className`, `BattleshipPreviewComponent`. |
+| `ChatPage` | Full-page chat: `theme`, `className`, `BattleshipPreviewComponent`. |
+| `ChatButton` | Launcher with unread badge; works outside the provider. `label`, `className`, `onClick`, `pressed`, `badgeClassName`, `iconSize`. Without `onClick` it toggles `chatUiStore`. |
+| `ChatNotifications` | Renders nothing; runs notification services while mounted (honors `config.notifications`). |
+| Hooks | `useChatConfig`, `useChatTransport`, `useChatConnection`, `useChatIdentity`, `useChatStore`, `useChatStoreApi`, `useChatUnreadTotal`, `useChatUi`, `useChatUnread`, `useChatGames`, `useChatInstall`, `useChatConnectionStatus` |
+| Transport and stores | `createStandaloneTransport`, `assertTransport`, `TRANSPORT_STATUSES`, `createChatStore`, `MAX_CHAT_MESSAGES`, `chatUiStore`, `chatGamesStore`, `chatConnectionStore`, `normalizeConfig`, `DEFAULT_CONFIG` |
+| Protocol helpers | `encodeEdit`, `encodeReaction`, `parseMessageAction`, `isMessageAction`, `groupReactions`, `isStickerAttachment`, `encodeEffect`, `decodeEffect`, `EFFECT_CATALOG`, `getChatEffect` |
+| WebRTC | `createPeerLink`, `createChatSignaling`, `rtcSignals`, `withSignalFaults`, `DEFAULT_ICE_SERVERS`, `WebRtcLab` (lazy, render inside `<Suspense>`), `encodeSignal`, `decodeSignal`, `isWebrtcMessage`, `WEBRTC_PREFIX`, `MAX_SIGNAL_LENGTH` |
+| Presentational | `ChatWindowShell`, `MessageList`, `MessageBubble`, `MessageComposer`, `EmojiPicker`, `GifPicker`, `StickerPicker`, `ChatPeopleContext` |
 
-For AI handoff and troubleshooting context, see [CONTEXTO_PARA_IA.md](CONTEXTO_PARA_IA.md)
-in the source repository (not included in the npm archive).
+`index.d.ts` has the full typed API. Anything not exported from the package root is internal.
 
-For the Spanish implementation record and demo walkthrough, see [NUEVAS_FUNCIONES.md](NUEVAS_FUNCIONES.md)
-in the source repository. This companion document is not included in the npm archive;
-the integration sections below are included.
+## Configuration
 
-## Custom image emojis
+`normalizeConfig` shallow-merges each section over `DEFAULT_CONFIG`. Keys that take effect today:
 
-Provide a catalog per chat provider. Custom shortcodes work in messages, the emoji picker,
-autocomplete and reactions. Unicode emojis continue to work normally.
+| Key | Default | Notes |
+|---|---|---|
+| `websocket.url` | `null` | String or (async) function. Used only when no `transport` is injected. |
+| `websocket.reconnect` | `{ max: 3, baseMs: 1000, capMs: 10000 }` | Reconnect backoff. |
+| `websocket.ping` | `false` | `{ action?, everyMs }` keep-alive. |
+| `auth.getToken`, `auth.tokenParam` | `null`, `'token'` | Token added to the WebSocket URL query. |
+| `user`, `scope` | `null` | User `{ id \| user_id \| sub, name \| username \| email }`; scope defaults to the user id. |
+| `features.youtube` | `true` | `false` disables players. |
+| `features.games.connect4`, `.battleship` | `true` | Set each to `false` to hide it. |
+| `features.games.tanks`, `.tanksLive` | `false` | Opt in. |
+| `features.detach` | `{ path: '/chat', windowName: 'lira-independent-chat' }` | `false` hides the detach button. `pwa.path`/`pwa.windowName` override it. |
+| `media.emoji.custom` | `[]` | [Custom emoji](#custom-image-emojis). |
+| `effects` | see [Effects](#effects) | `false` disables effects. |
+| `notifications.desktop`, `.sound`, `.appBadge` | `true` | Read by `<ChatNotifications />`; `notifications: false` disables all three. |
+| `webrtc.iceServers`, `.iceTransportPolicy` | `undefined`, `'all'` | Tanques LIVE STUN/TURN. |
+| `portalContainer` | `document.body` | Element or function for portals. |
+| `callbacks.onOpenChange`, `.onConnectionChange` | no-op | |
+
+Accepted and typed but **not wired yet** (no effect): `theme`, `locale`, `storage`, `assets.baseUrl`,
+`media.klipy`, `media.emoji.lazy`, `media.maxAttachmentBytes`, `media.trustedMediaHosts`,
+`notifications.previews` (users toggle previews in the chat header), `websocket.legacyRoomIdRouting`,
+`features.games.battleshipPreview`, the `features` flags `reactions`, `editing`, `replies`, `files`, `voice`,
+`gifs`, `stickers`, `presence`, `groups`, `privateChats` and `install`, and `callbacks.onError`,
+`onOpenConversation` and `onUnreadChange`. `features.games: false` and `features: false` currently do **not**
+hide Conecta 4 or Batalla Naval; disable them with the individual flags.
+
+## Emoji
+
+- Type `:` plus a name (for example `:smile`) for suggestions; an exact shortcode followed by `:` or a space
+  is converted. Classic emoticons (`:)`, `:D`, `;)`, `<3`…) are suggested as their emoji.
+- Recents, favorites and skin tone are stored locally per browser.
+
+### Custom image emojis
 
 ```jsx
 const config = {
@@ -204,41 +257,50 @@ const config = {
 };
 ```
 
-Use lowercase names of 1–32 letters, numbers, `_`, `+` or `-`. The catalog accepts up to
-100 entries. Unknown shortcodes or failed images remain readable as `:team_party:`.
-The consuming application supplies a shared catalog and image URLs for real users;
-it is responsible for upload permissions, storage and preserving images used in history.
-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.
-The pig uses `cerdito_disco_original.mp3`; nudge and confetti use `nudge.mp3` and `confetti.mp3`
-in the same `assets/sounds/effects/` directory. Serve
-`assets/sounds/effects/cerdito_disco_original.mp3` at `/sounds/effects/cerdito_disco_original.mp3`,
-or use the existing `setChatAssetsBaseUrl` sound asset configuration. Copying the complete
-`assets/sounds/` directory as described above includes this recording.
-Open the **Efectos y zumbidos** button in the composer and click an effect to send it
-and play its animation. Each compact row shows sending/sent feedback; sound and automatic
-playback are controlled by two switches. Received
-effects appear as cards with manual replay; new received effects play automatically by default in the visible conversation.
+Shortcodes are lowercase, 1–32 characters of letters, numbers, `_`, `+` or `-`; up to 100 entries; duplicates
+and entries without an HTTP(S), relative or raster `data:` URL are ignored. Unknown shortcodes or failed images
+stay readable as `:team_party:`. The host supplies the shared catalog and owns upload permissions, storage and
+keeping images used in history.
+
+## GIFs and stickers
+
+```js
+import { configureKlipy } from '@minicode-dev/chat';
+configureKlipy({ apiKey: yourKlipyAppKey }); // from your own config; never commit it
+```
+
+The key is sent from the browser in KLIPY request URLs. Optional `locale` (country code, default `do`) and
+`categoriesLocale` (default `es_DO`). Without a key, the pickers load nothing. Only media from KLIPY's hosts is
+accepted. Favorites and recents are local to the browser. GIFs and stickers are sent as attachments (see the
+checklist).
+
+## Attachments and voice notes
+
+Files from 1 byte to 10 MB, paste or pick; voice notes use `MediaRecorder` and need microphone permission
+(HTTPS or localhost). Both require an attachment-capable `sendMessage` (see the checklist).
+
+## YouTube
+
+Supported links: `watch?v=`, `youtu.be`, Shorts, Live and embed URLs (including start times), on
+`youtube.com`, `m.youtube.com`, `music.youtube.com` and `youtube-nocookie.com`. The first video per message is
+embedded from `youtube-nocookie.com`, lazy-loaded and without autoplay; the original text and an
+**Abrir en YouTube** link stay visible. No API key is needed. Videos must allow embedding.
+
+## Effects
+
+Open **✨ Efectos y zumbidos** in the composer and click an effect to send it. Allowed in private chats
+(and in groups with `allowGroups: true`).
+
+| ID | Name | Duration | Visual | Sound (`effects/`) |
+|---|---|---|---|---|
+| `nudge` | Zumbido ⚡ | 7 s | 3D thunderstorm, lightning and shake; Canvas 2D fallback | `nudge.mp3` |
+| `pig-disco` | Cerdito disco 🐷 | 5.2 s | Dancing SVG pig with disco ball | `cerdito_disco_original.mp3` |
+| `confetti` | Confeti 🎉 | 7 s | 3D party (confetti, balloons, gifts, streamers); 220-particle CSS fallback | `confetti.mp3` |
+| `avalanche` | Avalancha 🚀 | 7 s | 3D shower of money, cars, tanks and confetti; CSS fallback | `avalanche.mp3` |
+
+3D scenes load `three` lazily and sync with the recording. Without `three`/WebGL or after a lost WebGL context
+they use the fallback. With reduced motion, Confeti and Avalancha use the CSS fallback, Zumbido drops the shake
+and dims the flashes, and CSS animations stop.
 
 ```jsx
 const config = {
@@ -256,115 +318,90 @@ const config = {
 };
 ```
 
-Effects use ordinary versioned text messages over the existing transport; servers must
-preserve the message text. `encodeEffect`, `decodeEffect`, `EFFECT_PREFIX`, `EFFECT_CATALOG`
-and `getChatEffect` are exported for integrations. Older clients show a readable fallback
-alongside the versioned payload. Set `effects: false` to disable the feature.
-
-Audio requires browser permission to play after a user gesture and respects the chat's
-mute control. Effects stop when closed or when leaving the conversation; motion reduction
-uses a static alternative. History, duplicates and reconnection baselines do not trigger
-automatic playback. Automatic animations require a visible conversation in a visible tab.
-With `backgroundSound` (default `true`), an effect nobody is watching — hidden tab, closed
-chat window or another conversation — still plays its sound, like new-message sounds; returning
-to that conversation within `maxAgeMs` replays it with its animation. Same-origin
-tab deduplication is best effort. Receiving clients use a cooldown and ignore stale events.
-The server should enforce its own authorization and rate limits; browser controls alone
-cannot prevent abusive clients.
-
-In the demo, **Nuevas funciones** lets you simulate effects from Ana and configure playback.
-The demo permits effects in groups and uses the same 5-second cooldown. None of these
-features requires a paid audio API. Sharing full songs and managing a production emoji
-upload service are outside this implementation.
-
-## YouTube videos in messages
-
-Paste a YouTube video link into a message to display an inline player. Supported links
-include `watch?v=`, `youtu.be`, Shorts, Live and embed URLs, including start timestamps.
-The first supported video per message is embedded, with lazy loading and no autoplay.
-The original message is preserved and an **Abrir en YouTube** link is always available
-for videos that cannot play in an embedded player. No API key is required.
-
-Set `config.features.youtube` to `false` to disable previews. Playback requires internet
-access and a video that permits embedding. Applications with a Content Security Policy
-must allow `https://www.youtube-nocookie.com` in `frame-src`.
-
-## Proposed audio samples (demo only)
-
-Run `npm run dev`, open **Nuevas funciones**, and scroll to **Audios de los efectos**.
-The demo offers WAV previews of a disco/funk pig beat (104 BPM, two bars), a new nudge,
-and a festive confetti cue, alongside the current synthesized sounds for comparison.
-All three approved effects now use MP3 recordings. The pig WAV remains an alternative
-proposal; the nudge and confetti WAVs are the original sources of the approved recordings.
-
-`predev` generates the WAV files automatically. Use `npm run audio:samples` to regenerate
-them separately. Generated files live in `demo/audio-samples/`, are ignored by Git and
-excluded from npm. Source generators are in `demo/audio-lab/`; see
-[AUDIO_EFFECTS.md](AUDIO_EFFECTS.md) in the source repository for the arrangement and limitations.
-
-### Fun chat defaults
-
-New incoming effects automatically animate in the visible conversation by default;
-manual replay is still available. The default cooldown is 5 seconds. Window focus is
-not required; hidden tabs only play the sound (see `backgroundSound`) and old messages do not replay effects. A new permitted
-effect can replace the animation currently playing. Confetti fills the panel with
-220 colored particles and scales to its height. Reduced-motion preferences remain respected.
-Browsers can still block sound before the recipient interacts with the site; the visual
-effect does not depend on successful audio playback. Both participants must use an updated
-package, and explicitly saved `autoPlay: false` settings still disable automatic playback.
-
-## Tanques LIVE 3D (preview)
-
-This fourth game is independent of turn-based Tanks, Connect 4 and Battleship. Enable it explicitly:
+The values above are the defaults. Behavior:
+
+- Received effects appear as cards with **Reproducir efecto** and autoplay in the visible conversation of a
+  visible tab. A new effect can replace the one playing. Escape or **×** closes it.
+- With `backgroundSound`, an effect nobody is watching (hidden tab, closed window, another conversation) still
+  plays its sound; returning to that conversation within `maxAgeMs` replays it with the animation.
+- History, duplicates and events older than `maxAgeMs` do not autoplay. Sends and autoplay respect
+  `cooldownMs`. Same-origin tab deduplication is best effort.
+- The picker's **Sonido** and auto-play switches call `onPreferencesChange({ sound })` / `({ autoPlay })` so the
+  host can persist them. Browsers may block audio until the user interacts; visuals do not depend on it.
+- Receiving clients enforce cooldown and age limits, but the server should enforce its own authorization and
+  rate limits.
+
+### Countdown messages
+
+In the effects picker choose **Cuenta regresiva**, a duration (30 s, 1 min, 5 min, 10 min or a custom value in
+seconds or minutes, up to 24 hours), the final effect and whether it plays sound. **Probar efecto** previews it
+locally. The card shows a live clock, hides the chosen effect until zero (also in quotes and previews), animates
+the last ten seconds and plays the effect at zero in the visible conversation. Expired cards offer manual replay.
+Device clocks should be accurate.
+
+Effects and countdowns are ordinary text messages (`[minicode-effect:v1]` / `[minicode-countdown:v1]` plus
+JSON and a readable fallback line for older clients). No backend change is needed; the server must preserve the
+text.
+
+## Games
+
+All games are two-player, in private chats, started from the composer's games menu. Game events are chat
+messages with the `LIRA_GAME_V1:` prefix; they never appear as bubbles or unread messages.
+
+| Game | Flag (`features.games`) | Default | Rendering |
+|---|---|---|---|
+| Conecta 4 | `connect4` | `true` | DOM board |
+| Batalla Naval 3D | `battleship` | `true` | `three` scene; 2D grid fallback. Fleets stay private until the final reveal (commit–reveal). |
+| Tanques de guerra (turn-based) | `tanks` | `false` | `three` scene; Canvas 2D fallback. Deterministic simulation on both clients. |
+| Tanques LIVE 3D (real time) | `tanksLive` | `false` | `three` scene; Canvas 2D fallback. WebRTC DataChannels. |
+
+Optional Batalla Naval 3D preview (a local prototype opened from the games menu):
+
+```jsx
+import { lazy } from 'react';
+import { ChatWindow, loadBattleshipPreview } from '@minicode-dev/chat';
+
+const BattleshipPreview = lazy(loadBattleshipPreview);
+// <ChatWindow BattleshipPreviewComponent={BattleshipPreview} />
+```
+
+### Tanques LIVE 3D (preview)
 
 ```js
 const config = {
   features: { games: { tanksLive: true } },
-  // Optional: supply runtime STUN/TURN settings from your application.
+  // Optional: STUN/TURN supplied by your application at runtime.
   webrtc: { iceServers, iceTransportPolicy: 'all' },
 };
 ```
 
-Omit `webrtc` to use the existing default STUN servers. Never ship permanent TURN credentials.
-Both players need a compatible package version and a browser with WebRTC. Invitations and
-acceptance use the chat transport; movement and combat use DataChannels. The inviting player
-resolves damage. Three.js loads dynamically, with a Canvas 2D fallback. Shared game mute and
-volume settings apply to the existing tank sounds.
-
-For a local two-player test, run `npm run dev -- --host` and open
-`/tanks-live-lab.html?user=ana` and `/tanks-live-lab.html?user=luis` before inviting.
-Use WASD/arrows, mouse and click/space on desktop, or the joystick, arena touch aiming and fire
-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:
+- Simultaneous 1 vs 1 combat. Invitation and acceptance use the chat (`LIRA_GAME_V1:`); WebRTC signaling
+  (SDP/ICE) travels as `LIRA_WEBRTC_V1:` chat messages, at most 10,000 characters. Movement and combat use two
+  DataChannels; the inviting player resolves damage.
+- **The chat backend (for example Django) is only the signaling relay.** It needs no WebRTC endpoint or
+  protocol change and never carries game traffic, which goes peer to peer or through TURN.
+- Without `webrtc`, `DEFAULT_ICE_SERVERS` (public Google and Cloudflare STUN) is used. Never ship permanent TURN
+  credentials.
+- Controls: WASD/arrows, mouse and click/Space on desktop; joystick, touch aiming and fire button on mobile.
+  Minimizing keeps the match; reloading does not recover it. Shares the tank sounds and game mute/volume.
+
+#### Manual TURN recovery
+
+When a direct connection fails, either player can open **Configurar conexión alternativa** (also suggested
+after a slow or failed negotiation), paste temporary ICE credentials and choose **Aplicar y reconectar**. The
+other player receives and applies them automatically. Settings last for the current match only.
+
+- Accepted JSON: `{ "iceServers": [...] }` or a Cloudflare envelope `{ "success": true, "result": { "iceServers": [...] } }`,
+  optionally with `expiresAt` (ISO or Unix ms) or `expiresIn`/`ttl` (remaining seconds). The optional
+  **Validez restante en segundos** field is remaining validity, not the original TTL.
+- Rejected: invalid JSON, STUN-only sets, invalid ICE URLs (only `stun:`, `stuns:`, `turn:`, `turns:`), TURN
+  without password, known-expired credentials and API-token fields. Limits: 6,000 characters/bytes, 8 servers,
+  16 URLs.
+- Credentials are encrypted with an ephemeral ECDH/AES-GCM exchange before entering the chat; no plaintext
+  password is sent. Requires HTTPS (or localhost) and Web Crypto; without it, sharing fails safely. This relies
+  on the authenticated private-room relay and does not protect against a malicious signaling server.
+- **Never paste a permanent TURN API token.** Generate temporary credentials outside the app, for example
+  (credentials in your shell environment; copies the response to the macOS clipboard):
 
 ```sh
 curl --fail --silent --show-error \
@@ -374,59 +411,114 @@ curl --fail --silent --show-error \
   --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.
+- **Diagnóstico de conexión** shows SDP/ICE/DataChannel state, reconnects, RTT and sanitized errors, without
+  passwords, usernames, SDP or private addresses. `turnConfigured` only means a TURN URL is set;
+  `selectedPair.relay: true` means traffic actually uses TURN. **Forzar relay para diagnóstico** makes both
+  peers use `iceTransportPolicy: "relay"` to prove TURN works; turn it off for normal play.
+- Real-network behavior (Wi-Fi vs cellular, restrictive firewalls) needs testing on real devices; automated
+  tests use fake RTC/TURN.
+
+### 3D and `three`
+
+| Scene | Loaded | Without `three`/WebGL |
+|---|---|---|
+| Batalla Naval board and preview | When the board is shown / preview opened | 2D grid (preview needs WebGL) |
+| Tanques de guerra | When the match is shown | Canvas 2D |
+| Tanques LIVE | When the match starts | Canvas 2D |
+| Zumbido, Confeti, Avalancha | When the effect plays | Canvas 2D (Zumbido) or CSS |
+
+`three` never enters the main bundle; each scene is a separate chunk.
+
+## Wire protocol
+
+Everything travels over the chat transport. Special payloads are ordinary `CHAT_MESSAGE` text with a prefix,
+so the server only has to relay text unchanged, stamped with the sender's `user_id`.
+
+| Prefix | Purpose | Shown in history |
+|---|---|---|
+| `LIRA_EDIT_V1:` / `LIRA_REACT_V1:` | Edit / reaction on an earlier message | No (applied to the target) |
+| `sticker:` | Sticker attachment name | As a sticker |
+| `LIRA_GAME_V1:` | Game events (private rooms only) | No (game card) |
+| `LIRA_WEBRTC_V1:` | WebRTC signaling, including encrypted manual TURN | No, never counted as unread |
+| `[minicode-effect:v1]` / `[minicode-countdown:v1]` | Effects / countdowns | As effect cards |
+
+Requests carry a `request_id` and resolve on `CHAT_ACK` (or reject on a correlated `ERROR`). The frozen
+protocol is covered by `test/contract/`.
+
+## Local development
+
+```bash
+npm install
+npm run dev   # predev regenerates the demo WAV samples, then Vite opens the demo
+```
+
+The demo (`demo/`, not published) runs the library source with simulated users and in-memory messages: automatic
+replies, groups, emoji, custom emoji uploader, reactions, editing, attachments, voice notes, light/dark theme and
+**Nuevas funciones** (simulate incoming effects, playback settings, audio lab). No login or backend is needed.
+
+- **🪖 Tanques con Ana:** turn-based Tanques against a demo bot. Conecta 4 and Batalla Naval have no demo opponent.
+- **Tanques LIVE:** `npm run dev -- --host`, then open `/tanks-live-lab.html?user=ana` and `?user=luis` before
+  inviting (a dev-only Vite relay plays the chat server).
+- Labs: `/webrtc-lab.html`, `/tanks-lab.html`, `/avalanche-lab.html`.
+- GIF/sticker search needs your own KLIPY key (`configureKlipy`); the demo does not configure one.
+- Browser QA for manual TURN: `scripts/check-manual-turn-browser.mjs` (needs Playwright installed separately;
+  `CHAT_DEMO_URL`, `PLAYWRIGHT_MODULE`, `PLAYWRIGHT_EXECUTABLE_PATH`). It never uses real TURN credentials.
+- Tests use Node's runner, for example `node --test test/effects/*.test.mjs test/unit/*.test.mjs`. See
+  `docs/desarrollo/demo-y-pruebas.md` for every suite.
+
+### Audio audition lab (demo only)
+
+**Nuevas funciones → Audios de los efectos** plays procedurally generated WAVs next to the shipped MP3
+(**Escuchar audio integrado**). `predev` runs `npm run audio:samples`, which writes them to `demo/audio-samples/`
+(git-ignored, not published) from the generators in `demo/audio-lab/`:
+
+- `pig-disco.wav` (~5 s, 104 BPM): an alternative proposal; the shipped pig is `cerdito_disco_original.mp3`.
+- `nudge.wav` (0.9 s) and `confetti.wav` (2.7 s): sources of the earlier short cues only. The current ~7 s
+  `nudge.mp3` and `confetti.mp3` are separate recordings and do not come from these WAVs.
+- Avalancha has no WAV; `avalanche.mp3` is its approved ~7 s recording.
+
+The lab's own text still calls the nudge and confetti WAVs the sources of the current recordings; that is out of
+date. Details: `docs/funciones/efectos.md` (section "Audio").
+
+### Build, pack and source mode
+
+```bash
+npm run build  # ESM library, lazy chunks and dist/styles.css
+npm pack       # builds again via prepack and creates minicode-dev-chat-<version>.tgz
+```
+
+Install the tarball in a React app to test (`npm install /path/to/minicode-chat/minicode-dev-chat-<version>.tgz`)
+and repeat after each change. The custom `@minicode-dev/source` export condition points at `src/`; tooling must
+enable it explicitly (for example Vite `resolve.conditions`) and React and the other peers must resolve to one copy.
+
+## Publishing updates
+
+Log in with `npm login`, then:
+
+```bash
+npm run release                 # patch version, build, validate contents, publish
+npm run release -- minor        # minor version
+npm run release -- major        # major version
+npm run release -- --dry-run    # build and inspect; no version change or publication
+```
+
+The script checks your npm session, builds, bumps the version without a Git commit or tag, and validates the exact
+archive (only `dist/`, `assets/`, `index.d.ts`, `README.md`, `CHANGELOG.md` and `package.json`) before
+publishing. Temporary archives and root `.tgz` files are removed even on failure; `dist/` is kept. If publication
+fails after the bump, the new version stays in `package.json` and the lockfile. No Git push is performed. The
+script is called `release` because npm reserves `publish` as a lifecycle hook.
+
+## Documentation
+
+Internal docs (Spanish) live in the source repository and are not published to npm:
+
+- [docs/README.md](docs/README.md): index.
+- [docs/contexto-para-ia.md](docs/contexto-para-ia.md): rules, status, code map, protocols and pending work.
+- Features: [docs/funciones/README.md](docs/funciones/README.md), [efectos.md](docs/funciones/efectos.md),
+  [emojis-personalizados.md](docs/funciones/emojis-personalizados.md), [youtube.md](docs/funciones/youtube.md).
+- Games: [docs/juegos/README.md](docs/juegos/README.md),
+  [Tanques LIVE progress](docs/juegos/tanques-live/progreso-webrtc.md).
+- Development: [demo-y-pruebas.md](docs/desarrollo/demo-y-pruebas.md),
+  [integracion-consumidor.md](docs/desarrollo/integracion-consumidor.md),
+  [publicacion.md](docs/desarrollo/publicacion.md).
+- Changes per version: [CHANGELOG.md](CHANGELOG.md).