@minicode-dev/chat 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to `@minicode-dev/chat` (owner: Minicode, project: LIRA).
+
+## 0.1.0 (unreleased)
+
+First release extracted from LIRA.
+
+### Added
+
+- Package inside the LIRA npm workspace (`packages/chat`), restricted publish under the `@minicode-dev` scope.
+- `LiraChatProvider` with `config` / `transport` / `stores` / `chatStore`, `normalizeConfig` and `DEFAULT_CONFIG`.
+- `ChatTransport` contract, `createStandaloneTransport` and the LIRA transport adapter.
+- Connected placements `ChatWindow`, `ChatPage`, `ChatButton`, `ChatNotifications`, plus presentational primitives
+  (`ChatWindowShell`, `MessageList`, `MessageBubble`, `MessageComposer`, emoji/GIF/sticker pickers).
+- Frozen protocol helpers (`LIRA_EDIT_V1:` / `LIRA_REACT_V1:` prefixes, stickers, reactions).
+- Games (Connect 4, Battleship 3D with optional `three`), notifications and PWA helpers.
+- Library build (Vite, ESM) to `dist/index.js` + `dist/styles.css`; hand-written `index.d.ts`.
+- Sounds shipped in `assets/sounds/`, served by the host (`setChatAssetsBaseUrl`).
+
+### Changed
+
+- `emojibase-data` is loaded lazily with dynamic `import()` (cached); the emoji picker and autocomplete
+  re-render when the catalog arrives (`useEmojiDataReady`).

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# @minicode-dev/chat
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Real-time chat for React (WebSocket, reactions, editing, emoji, GIFs/stickers via KLIPY, file and voice
+attachments, notifications, Connect 4 and 3D Battleship) extracted from LIRA.
+
+- Owner: **Minicode** · Project: **LIRA** · License: UNLICENSED (private, internal use only).
+- Migration plan and status: `docs/MBSoft-Chat-NPM-Migration.md` in the LIRA repository.
+
+## Installation (private registry)
+
+The package is published as a **restricted** package under the `@minicode-dev` scope. Add an `.npmrc` to the
+host project (keep the token out of git, e.g. via an environment variable):
+
+```ini
+@minicode-dev:registry=https://registry.npmjs.org/
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}
+```
+
+```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"
+```
+
+### Peer dependencies
+
+| Package | 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). |
+
+`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).
+
+## Usage
+
+```jsx
+import {
+  LiraChatProvider, ChatButton, ChatWindow, ChatPage, ChatNotifications,
+} 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) },
+};
+
+export function App() {
+  return (
+    <LiraChatProvider config={config}>
+      <ChatButton label="Chat" />
+      <ChatWindow placement="floating" />
+      <ChatNotifications />
+    </LiraChatProvider>
+  );
+}
+
+// Full-page route (e.g. /chat, also used by the "detach" window):
+export function ChatRoute() {
+  return (
+    <LiraChatProvider config={config}>
+      <ChatPage />
+    </LiraChatProvider>
+  );
+}
+```
+
+- `LiraChatProvider` props: `config`, `transport` (inject your own `ChatTransport`, e.g. the LIRA 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)
+
+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:
+
+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
+   ```
+
+2. Or serve them from another path/CDN and point the chat at it, before any sound plays:
+
+   ```js
+   import { setChatAssetsBaseUrl } from '@minicode-dev/chat';
+   setChatAssetsBaseUrl('https://cdn.example.com/minicode-chat/sounds');
+   ```
+
+   (`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.
+
+## Development (LIRA workspace)
+
+Inside the LIRA repo the package lives in `packages/chat` and is consumed **from source** through the
+aliases in the root `vite.config.js`. The exports also carry a custom `@minicode-dev/source` condition that
+points at `src/` for tooling that opts into it (`resolve.conditions`); it is never resolved by default.
+
+```bash
+npm run build:chat          # vite library build -> packages/chat/dist (index.js + styles.css)
+npm pack -w @minicode-dev/chat  # runs prepack (build) and creates the tarball
+npm publish -w @minicode-dev/chat
+```