@minicode-dev/chat 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to `@minicode-dev/chat` (owner: Minicode, project: LIRA).
 
+## Unreleased
+
+### Added
+
+- Custom image emoji catalogs per provider, with picker, autocomplete and reaction support.
+- Compact, one-click effects picker with sending feedback and sound/autoplay preferences.
+- Nudge, dancing pig and confetti effects with the approved MP3 recordings in `assets/sounds/effects/`.
+- Inline YouTube players for supported links, with a link to open YouTube.
+- Source-based local demo, simulated conversations and an audio audition laboratory.
+
+### Changed
+
+- Incoming effects autoplay by default in visible conversations, with a 5-second cooldown and no window-focus requirement.
+- New incoming effects can replace an active animation; confetti now fills the panel with 220 responsive particles.
+
+- Effects respect mute, reduced motion, cooldowns and manual replay; old messages and duplicates do not autoplay.
+- Standalone development and release documentation. Host applications must update their served sound assets.
+
 ## 0.1.0 (unreleased)
 
 First release extracted from LIRA.

package/README.md

@@ -99,7 +99,8 @@ from `/sounds/...`. Either:
 1. Copy them into the host's public folder, e.g. in a `postinstall`/build step:
 
    ```bash
-   cp -R node_modules/@minicode-dev/chat/assets/sounds public/sounds
+   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:
@@ -115,7 +116,21 @@ The files are also exposed as `@minicode-dev/chat/assets/*` for bundlers that ca
 
 ## Local development
 
-This repository builds a library; it does not include a standalone demo or a `dev` script.
+This repository includes a local React demo that consumes the library source directly:
+
+```bash
+npm install
+npm run dev
+```
+
+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.
+
+To build or pack the library:
 
 ```bash
 npm install
@@ -162,3 +177,118 @@ npm authentication challenge are handled by you. No Git push is performed.
 
 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.
+
+## Feature implementation notes
+
+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).
+
+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.
+
+## Custom image emojis
+
+Provide a catalog per chat provider. Custom shortcodes work in messages, the emoji picker,
+autocomplete and reactions. Unicode emojis continue to work normally.
+
+```jsx
+const config = {
+  media: {
+    emoji: {
+      custom: [
+        { shortcode: 'team_party', url: 'https://your-app.example/emojis/party.webp', label: 'Team party' },
+      ],
+    },
+  },
+};
+```
+
+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.
+
+## 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.
+
+```jsx
+const config = {
+  effects: {
+    enabled: true,
+    autoPlay: true,
+    sound: true,
+    volume: 0.35,
+    cooldownMs: 5000,
+    maxAgeMs: 10000,
+    allowGroups: false,
+    onPreferencesChange: (patch) => console.log('Save user preferences', patch),
+  },
+};
+```
+
+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 effects require a visible conversation in a visible tab. 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, but hidden tabs 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.