@minicode-dev/chat 0.0.0-stage → 0.1.1

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,164 @@
-# 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).
+
+Standalone, reusable npm package for integration into React applications through configurable
+providers and transport adapters.
+
+- Owner: **Minicode** · License: `UNLICENSED`.
+
+## Installation
+
+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):
+
+```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` 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.
+
+## Local development
+
+This repository builds a library; it does not include a standalone demo or a `dev` script.
+
+```bash
+npm install
+npm run build  # ESM library and styles in dist/
+npm pack       # builds again via prepack and creates an installable .tgz
+```
+
+To test local changes, install the generated tarball in a React application:
+
+```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
+```
+
+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
+
+Log in yourself with `npm login`, then run:
+
+```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 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.
+
+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.