@composy/chat-core 0.0.1 → 0.0.2

package/README.md

@@ -1,123 +1,187 @@
-# @composy/chat-core
-
-Framework-agnostic chat runtime for LDesign. It renders message lists, bubbles, input, mentions, toolbar actions, voice input hooks, upload/drop callbacks, message status, streaming text, and light/dark/auto themes without depending on a UI framework.
-
-## Features
-
-- Text, image, file, system, custom, revoked, and streaming messages.
-- Mention engine with keyboard navigation, name/id filtering, and mention parsing.
-- Toolbar callbacks for image upload, file upload, paste, drop, and browser speech recognition.
-- Input helpers: `enterToSend`, `clearInputOnSend`, `maxInputLength`, `setInputContent`, `clearInput`, and `onInputChange`.
-- Runtime APIs for message CRUD, streaming append/finish, scroll control, loading-more state, and message lookup.
-- All generated classes use the `ldesign-` prefix. The default class prefix is `ldesign-chat`.
-- Component CSS variables use `--ldesign-chat-*` and map to shared `packages/color` `--color-*` variables plus `packages/size` `--size-*` variables.
-
-## Install
-
-```bash
-pnpm add @composy/chat-core
-```
-
-Load the global LDesign color and size variable styles before mounting chat UI:
-
-```ts
-import '@composy/color-core/styles.css';
-import '@composy/size-core/styles.css';
-```
-
-## Usage
-
-```ts
-import { createChat } from '@composy/chat-core';
-
-const chat = createChat({
-  container: '#chat',
-  currentUserId: 'u1',
-  theme: 'auto',
-  enableMention: true,
-  mentionMembers: [
-    { id: 'u2', name: 'Alice' },
-  ],
-  onSend(content, mentions) {
-    console.log(content, mentions);
-  },
-});
-
-chat.addMessage({
-  id: 'm1',
-  type: 'text',
-  direction: 'incoming',
-  sender: { id: 'u2', nickname: 'Alice' },
-  content: 'Hello',
-  timestamp: Date.now(),
-});
-```
-
-## Public API
-
-```ts
-chat.addMessage(message);
-chat.prependMessages(messages);
-chat.updateMessage(id, updates);
-chat.removeMessage(id);
-chat.setMessages(messages);
-chat.clearMessages();
-chat.getMessages();
-chat.getMessage(id);
-
-chat.appendMessageContent(id, chunk);
-chat.finishStreaming(id);
-
-chat.scrollToBottom(true);
-chat.isAtBottom();
-chat.setLoadingMore(false);
-
-chat.setTheme('dark');
-chat.setMentionMembers(members);
-
-chat.focusInput();
-chat.setInputContent('hello');
-chat.getInputContent();
-chat.clearInput();
-
-chat.on('message-retry', (message) => {});
-chat.destroy();
-```
-
-## Styling Contract
-
-The renderer normalizes `classPrefix`. If no prefix is passed, generated classes start with `ldesign-chat-*`. If a custom prefix does not start with `ldesign-`, it is normalized to `ldesign-${prefix}`.
-
-Key classes:
-
-- `ldesign-chat-container`
-- `ldesign-chat-message-list`
-- `ldesign-chat-message-row`
-- `ldesign-chat-bubble`
-- `ldesign-chat-input-area`
-- `ldesign-chat-toolbar`
-- `ldesign-chat-mention-panel`
-
-The injected stylesheet defines component variables such as:
-
-- `--ldesign-chat-bg-primary`
-- `--ldesign-chat-text-primary`
-- `--ldesign-chat-border-primary`
-- `--ldesign-chat-avatar-size`
-- `--ldesign-chat-radius-md`
-- `--ldesign-chat-transition-fast`
-
-Defaults are references to `--color-*` and `--size-*` tokens, so consumers can theme chat by loading or overriding the shared token styles.
-
-## Build
-
-```bash
-pnpm --dir libraries/chat/packages/core type-check
-pnpm --dir libraries/chat/packages/core build
-```
-
-The build generates `dist`, `es`, `esm`, and `lib`. `postbuild` verifies required outputs and creates `dist/index.min.js`.
-
-## License
-
-MIT
+# @composy/chat-core
+
+Framework-agnostic chat runtime for LDesign. It renders message lists, bubbles, input, mentions,
+toolbar actions, voice input hooks, upload/drop callbacks, message status, streaming text, and
+light/dark/auto themes without depending on a UI framework.
+
+## Features
+
+- Text, image, file, system, custom, revoked, and streaming messages.
+- Mention engine with keyboard navigation, name/id filtering, and mention parsing.
+- Toolbar callbacks for image upload, file upload, paste, drop, and browser speech recognition.
+- Input helpers: `enterToSend`, `clearInputOnSend`, `maxInputLength`, `setInputContent`,
+  `clearInput`, and `onInputChange`.
+- Runtime APIs for message CRUD, streaming append/finish, scroll control, loading-more state, and
+  message lookup.
+- Versioned `ChatContentBlock` schema for text, mention, link, code, image, file, break, and custom
+  fallback content; unknown runtime blocks are dropped or rendered as safe text.
+- Idempotent remote merge by `id`/`clientMessageId` with `sequence` filtering, plus transport
+  lifecycle (`connect`/`disconnect`/ack/cursor/error) for HTTP, SSE, WebSocket, or native bridges.
+- Offline `ChatOutbox` with replaceable persistence, bounded retry, abort support, attempt tracking,
+  and stable idempotency keys.
+- All generated classes use the `ldesign-` prefix. The default class prefix is `ldesign-chat`.
+- Component CSS variables use `--ldesign-chat-*` and map to the generated `--ld-*` color and size
+  variables from `packages/color` and `packages/size`.
+- Theme variables are applied per chat instance, so instances can use different themes and can live
+  in separate documents such as iframes.
+- Custom HTML messages are sanitized. Scriptable elements, event attributes, inline styles, and
+  unsafe URLs are removed; basic text, formatting, list, link, and image elements are supported.
+
+## Install
+
+```bash
+pnpm add @composy/chat-core
+```
+
+Load the global LDesign color and size variable styles before mounting chat UI:
+
+```ts
+import '@composy/color-core/styles.css'
+import '@composy/size-core/styles.css'
+```
+
+## Usage
+
+```ts
+import { createChat } from '@composy/chat-core'
+
+const chat = createChat({
+  container: '#chat',
+  currentUserId: 'u1',
+  theme: 'auto',
+  enableMention: true,
+  mentionMembers: [{ id: 'u2', name: 'Alice' }],
+  onSend(content, mentions) {
+    console.info(content, mentions)
+  },
+})
+
+chat.addMessage({
+  id: 'm1',
+  type: 'text',
+  direction: 'incoming',
+  sender: { id: 'u2', nickname: 'Alice' },
+  content: 'Hello',
+  timestamp: Date.now(),
+})
+
+chat.addMessage({
+  id: 'm2',
+  type: 'custom',
+  direction: 'incoming',
+  sender: { id: 'u2', nickname: 'Alice' },
+  contentBlocks: [
+    { type: 'text', text: 'See ' },
+    { type: 'link', url: 'https://example.com', label: 'the docs' },
+    { type: 'break' },
+    { type: 'code', code: 'pnpm add @composy/chat-core' },
+  ],
+  timestamp: Date.now(),
+})
+```
+
+## Public API
+
+```ts
+chat.addMessage(message)
+chat.prependMessages(messages)
+chat.updateMessage(id, updates)
+chat.removeMessage(id)
+chat.setMessages(messages)
+chat.clearMessages()
+chat.getMessages()
+chat.getMessage(id)
+
+chat.beginStreaming(id, generation)
+chat.appendMessageContent(id, chunk, { generation, sequence })
+chat.finishStreaming(id, generation)
+chat.cancelStreaming(id, generation)
+
+chat.mergeMessage(remoteMessage, sequence)
+chat.connectTransport(signal)
+chat.disconnectTransport()
+chat.getTransportStatus()
+chat.sendMessage(message, { signal })
+chat.flushOutbox({ maxAttempts, concurrency, signal })
+
+chat.scrollToBottom(true)
+chat.isAtBottom()
+chat.setLoadingMore(false)
+
+chat.setTheme('dark')
+chat.setMentionMembers(members)
+
+chat.focusInput()
+chat.setInputContent('hello')
+chat.getInputContent()
+chat.clearInput()
+
+chat.on('message-retry', message => console.info(message))
+chat.destroy()
+```
+
+For AI or network streams, use a generation and monotonically increasing chunk sequence. A late
+chunk from a previous generation then returns `false` instead of mutating the current message:
+
+```ts
+const generation = chat.beginStreaming('m3', 'reply-1')
+chat.appendMessageContent('m3', '第一段', { generation, sequence: 1 })
+chat.appendMessageContent('m3', '第二段', { generation, sequence: 2 })
+chat.finishStreaming('m3', generation)
+```
+
+`ChatConfig.transport` accepts any adapter implementing `ChatTransport`. `sendMessage()` creates a
+stable `clientMessageId`, marks the local message as `sending`, applies the server ack, and marks it
+`failed` on error. Configure `outbox: new ChatOutbox()` when failed messages should survive an
+offline period and call `flushOutbox()` after reconnecting.
+
+## Styling Contract
+
+The renderer normalizes `classPrefix`. If no prefix is passed, generated classes start with
+`ldesign-chat-*`. If a custom prefix does not start with `ldesign-`, it is normalized to
+`ldesign-${prefix}`.
+
+Key classes:
+
+- `ldesign-chat-container`
+- `ldesign-chat-message-list`
+- `ldesign-chat-message-row`
+- `ldesign-chat-bubble`
+- `ldesign-chat-input-area`
+- `ldesign-chat-toolbar`
+- `ldesign-chat-mention-panel`
+
+The injected stylesheet defines component variables such as:
+
+- `--ldesign-chat-bg-primary`
+- `--ldesign-chat-text-primary`
+- `--ldesign-chat-border-primary`
+- `--ldesign-chat-avatar-size`
+- `--ldesign-chat-radius-md`
+- `--ldesign-chat-transition-fast`
+
+Defaults reference `--ld-*` color and size tokens, so consumers should load the shared Color and
+Size styles before mounting chat. Each instance keeps its theme overrides on its own root element.
+
+Calling `getMessage()` or `getMessages()` returns defensive copies. Message IDs must be non-empty
+and unique within the list, and an existing message ID cannot be changed with `updateMessage()`.
+Load-more callback rejections are caught and emitted as `load-more-error` through `chat.on()`.
+Messages entering the manager are normalized to schema version 1. Remote messages with an older
+`sequence` are ignored. Use `clientMessageId` as the server idempotency key and persist failed
+messages with `ChatOutbox` when the transport can be offline.
+
+## Build
+
+```bash
+pnpm run type-check
+pnpm run type-check:cjs
+pnpm run build
+```
+
+TypeScript ESM/CJS configurations and the rolldown Builder configuration live in `.ldesign/`. The
+build generates `dist`, `es`, `esm`, and `lib`; `postbuild` normalizes and validates the package
+outputs against the manifest.
+
+## License
+
+MIT