quikchat 1.1.16 → 1.2.4

package/README.md

@@ -1,442 +1,248 @@
-[![License](https://img.shields.io/badge/License-BSD%202--Clause-blue.svg)](https://opensource.org/licenses/BSD-2-Clause) [![NPM version](https://img.shields.io/npm/v/quikchat.svg?style=flat-square)](https://www.npmjs.com/package/quikchat) ![CI](https://github.com/deftio/quikchat/actions/workflows/ci.yml/badge.svg)
+[![License](https://img.shields.io/badge/License-BSD%202--Clause-blue.svg)](https://opensource.org/licenses/BSD-2-Clause)
+[![NPM version](https://img.shields.io/npm/v/quikchat.svg?style=flat-square)](https://www.npmjs.com/package/quikchat)
+![CI](https://github.com/deftio/quikchat/actions/workflows/ci.yml/badge.svg)
 
 # QuikChat
 
-> Zero-dependency JavaScript chat widget for modern web applications
+A lightweight, zero-dependency vanilla JavaScript chat widget. Drop it into any page — no React, no Vue, no build step required — and connect it to any LLM, WebSocket, or message source with plain `fetch()`.
 
-QuikChat is a lightweight, highly customizable chat interface that integrates seamlessly with any web project. Built with vanilla JavaScript, it provides powerful features for LLM applications, real-time chat, and interactive messaging experiences.
-
-**🚀 [Live Demo](https://deftio.github.io/quikchat/examples/example_umd.html) | 📚 [API Reference](docs/API-REFERENCE.md) | 🛠 [Developer Guide](docs/DEVELOPER-GUIDE.md)**
+```html
+<script src="https://unpkg.com/quikchat"></script>
+<link rel="stylesheet" href="https://unpkg.com/quikchat/dist/quikchat.css" />
+```
 
+```javascript
+const chat = new quikchat('#chat', async (chat, msg) => {
+    chat.messageAddNew(msg, 'me', 'right', 'user');
 
+    // Stream a response from any LLM
+    const id = chat.messageAddTypingIndicator('bot');
+    const response = await fetch('http://localhost:11434/api/chat', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            model: 'llama3.1',
+            messages: chat.historyGet(),   // full conversation context
+            stream: true
+        })
+    });
 
-## ✨ Key Features
+    const reader = response.body.getReader();
+    let first = true;
+    while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        const token = JSON.parse(new TextDecoder().decode(value).trim()).message.content;
+        if (first) { chat.messageReplaceContent(id, token); first = false; }
+        else       { chat.messageAppendContent(id, token); }
+    }
+});
+```
 
-- **🚫 Zero Dependencies** - Pure vanilla JavaScript, no frameworks required
-- **🎨 Fully Customizable** - Complete CSS theming system with multi-instance support
-- **🤖 LLM Ready** - Built-in support for OpenAI, Anthropic, Ollama, and streaming responses
-- **📱 Responsive Design** - Adapts to any screen size and container dimensions
-- **⚡ High Performance** - Virtual scrolling for large message volumes
-- **👁 Advanced Visibility** - Individual and group-based message control (v1.1.13+)
-- **🏷 Tagged Messages** - Powerful tagging system for message organization (v1.1.14+)
-- **💾 Full History Control** - Save, load, and restore complete chat sessions
-- **🔧 Developer Friendly** - TypeScript-ready with comprehensive API
+That's a working streaming LLM chat in one file — no bundler, no framework, no SDK.
 
+## Features
 
+- **LLM-ready** — `historyGet()` returns `{ role, content }` objects compatible with OpenAI, Ollama, Mistral, and Claude APIs
+- **Streaming built in** — `messageAddNew()` → `messageAppendContent()` for token-by-token display
+- **Typing indicator** — animated "..." dots that auto-clear when streaming begins
+- **Markdown support** — three tiers: base (no markdown), `-md` (basic markdown via [quikdown](https://github.com/deftio/quikdown)), `-md-full` (syntax highlighting, math, diagrams, maps — loaded on demand from CDN)
+- **HTML sanitization** — built-in XSS protection or plug in your own sanitizer
+- **Themeable** — 8 built-in CSS themes (light, dark, blue, warm, midnight, ocean, modern, debug) or write your own
+- **Multi-user** — multiple users per chat, multiple independent chats per page
+- **Message visibility & tagging** — hide system prompts and tool-call results from the UI while keeping them in history for LLM context
+- **History export / import** — save and restore complete chat sessions (`historyExport()` / `historyImport()`)
+- **RTL support** — `setDirection('rtl')` for Arabic, Hebrew, and other right-to-left languages
+- **Event callbacks** — hooks for message add, append, replace, and delete events
+- **Timestamps** — optional per-message timestamps (show/hide)
+- **Zero runtime dependencies** — ~5 KB gzipped (base), ~9 KB with markdown, ~14 KB full
+- **Any environment** — works with CDN, npm, or local files; UMD, ESM, and CJS builds included
+- **Responsive** — fills its parent container and resizes automatically
+- **Accessible** — ARIA roles and labels on all interactive elements
 
-## 🚀 Quick Start
+## Quick Start
 
-Get a working chat interface in under 60 seconds:
+### CDN
 
-### Via CDN
 ```html
-<!DOCTYPE html>
-<html>
-<head>
-    <link rel="stylesheet" href="https://unpkg.com/quikchat/dist/quikchat.css">
-</head>
-<body>
-    <div id="chat" style="width: 100%; height: 400px;"></div>
-    
-    <script src="https://unpkg.com/quikchat"></script>
-    <script>
-        const chat = new quikchat('#chat', (instance, message) => {
-            // Echo user message
-            instance.messageAddNew(message, 'You', 'right');
-            
-            // Add bot response
-            setTimeout(() => {
-                instance.messageAddNew('Thanks for your message!', 'Bot', 'left');
-            }, 1000);
-        });
-        
-        // Add welcome message
-        chat.messageAddNew('Hello! How can I help you today?', 'Bot', 'left');
-    </script>
-</body>
-</html>
+<script src="https://unpkg.com/quikchat"></script>
+<link rel="stylesheet" href="https://unpkg.com/quikchat/dist/quikchat.css" />
 ```
 
-### Via NPM
+### npm
+
 ```bash
 npm install quikchat
 ```
 
 ```javascript
 import quikchat from 'quikchat';
-import 'quikchat/dist/quikchat.css';
-
-const chat = new quikchat('#chat-container', (instance, message) => {
-    // Your message handling logic
-    console.log('User said:', message);
-});
 ```
 
+### With Markdown
 
-
-## 📦 Installation Options
-
-### NPM Package
-```bash
-npm install quikchat
-```
-
-### CDN (Latest Version)
 ```html
-<!-- CSS -->
-<link rel="stylesheet" href="https://unpkg.com/quikchat/dist/quikchat.css">
-
-<!-- JavaScript -->
-<script src="https://unpkg.com/quikchat"></script>
-```
-
-### Direct Download
-Download the latest release from [GitHub Releases](https://github.com/deftio/quikchat/releases)
-
-
-
-## 🆕 What's New in v1.1.16
-
-### ⚡ Virtual Scrolling for High Performance
-QuikChat now includes built-in virtual scrolling that handles 10,000+ messages efficiently. Only visible messages are rendered in the DOM, providing massive performance improvements:
+<!-- Basic markdown (bold, italic, code, tables, lists) — ~9 KB gzip -->
+<script src="https://unpkg.com/quikchat/dist/quikchat-md.umd.min.js"></script>
 
-- **10,000 messages**: Renders in 38ms (vs 146 seconds without)
-- **Memory efficient**: ~2MB for 10,000 messages (vs ~187MB without)
-- **Automatic activation**: Enables at 500+ messages by default
-- **Dynamic height support**: Handles variable-length LLM responses
+<!-- Full markdown (+ syntax highlighting, math, diagrams, maps) — ~14 KB gzip -->
+<script src="https://unpkg.com/quikchat/dist/quikchat-md-full.umd.min.js"></script>
 
-```javascript
-// Virtual scrolling is enabled by default
-const chat = new quikchat('#chat', handler);
-
-// Check if virtual scrolling is active
-if (chat.isVirtualScrollingEnabled()) {
-    console.log('Virtual scrolling is active');
-}
-
-// Get virtual scrolling configuration
-const config = chat.getVirtualScrollingConfig();
-console.log(`Enabled: ${config.enabled}, Threshold: ${config.threshold}`);
-
-// Disable if needed for specific use cases
-const customChat = new quikchat('#custom-chat', handler, {
-    virtualScrolling: false
-});
+<link rel="stylesheet" href="https://unpkg.com/quikchat/dist/quikchat.css" />
 ```
 
-### 🎯 Smart Scroll Behavior
-Improved user experience when reading chat history:
+The `-md-full` build uses [quikdown](https://github.com/deftio/quikdown)'s editor as a rendering engine. When your LLM returns a fenced code block with a language tag, highlight.js loads from CDN automatically. Same for math (MathJax), diagrams (Mermaid), and maps (Leaflet) — each loads on demand the first time it's encountered.
 
-```javascript
-// Never auto-scroll (user has full control)
-chat.messageAddNew('New message', 'Bot', 'left', 'assistant', false);
+Same API across all three builds — just pick your script tag.
 
-// Smart scroll - only scrolls if user is near bottom
-chat.messageAddNew('New message', 'Bot', 'left', 'assistant', 'smart');
-
-// Always scroll to new messages (default)
-chat.messageAddNew('New message', 'Bot', 'left', 'assistant', true);
-```
-
-### 🔔 Enhanced Message Callbacks
-Track message modifications for streaming and real-time updates:
+## Usage
 
 ```javascript
-// Track streaming content as it arrives
-chat.setCallbackonMessageAppend((instance, msgId, content) => {
-  console.log(`Streaming: ${content} added to message ${msgId}`);
-});
-
-// Monitor message edits
-chat.setCallbackonMessageReplace((instance, msgId, newContent) => {
-  console.log(`Message ${msgId} updated`);
-});
+const chat = new quikchat(
+    '#chat-container',           // CSS selector or DOM element
+    (chat, msg) => {             // onSend callback
+        chat.messageAddNew(msg, 'me', 'right');
+    },
+    {
+        theme: 'quikchat-theme-light',
+        titleArea: { title: 'My Chat', align: 'left', show: true },
+    }
+);
 
-// Track deletions
-chat.setCallbackonMessageDelete((instance, msgId) => {
-  console.log(`Message ${msgId} deleted`);
-});
-```
+// Add messages programmatically
+chat.messageAddNew('Hello!', 'Alice', 'left', 'user');
+chat.messageAddNew('Hi there!', 'Bot', 'left', 'assistant');
+chat.messageAddNew('System notice', 'system', 'center', 'system');
 
-### 📚 Powerful History Management
-Efficiently handle large chat histories with pagination and search:
+// Streaming pattern
+const id = chat.messageAddTypingIndicator('bot');     // show "..." dots
+chat.messageReplaceContent(id, firstToken);            // first token clears dots
+chat.messageAppendContent(id, nextToken);              // append subsequent tokens
 
-```javascript
-// Paginated history retrieval
-const page = chat.historyGetPage(1, 20, 'desc'); // Get newest 20 messages
-console.log(page.messages);
-console.log(page.pagination.hasNext); // Check if more pages exist
-
-// Search through history
-const results = chat.historySearch({ 
-  text: 'error',
-  userString: 'Support',
-  limit: 50 
-});
+// Disable input while bot is responding
+chat.inputAreaSetEnabled(false);
+chat.inputAreaSetButtonText('Thinking...');
+// ... after response completes ...
+chat.inputAreaSetEnabled(true);
+chat.inputAreaSetButtonText('Send');
 
-// Get history metadata
-const info = chat.historyGetInfo();
-console.log(`Total messages: ${info.totalMessages}`);
-console.log(`Memory used: ${info.memoryUsage.estimatedSize} bytes`);
+// History is LLM-API compatible
+const history = chat.historyGet();  // [{ role: "user", content: "..." }, ...]
 ```
 
-## 📦 Previous Release: v1.1.14
+## Message Formatter & Sanitization
 
-### 🏷 Tagged Message System
-Group and control message visibility with powerful tagging:
+Process message content before display — render markdown, sanitize HTML, or both:
 
 ```javascript
-// Add messages with tags
-chat.messageAddNew('System initialized', 'System', 'center', 'system', true, true, ['system', 'startup']);
-
-// Control visibility by tag
-chat.setTagVisibility('system', false); // Hide all system messages
-chat.setTagVisibility('system', true);  // Show all system messages
+const chat = new quikchat('#chat', onSend, {
+    // Sanitize user input (true = escape HTML entities, or pass a function)
+    sanitize: true,
 
-// Get active tags
-const tags = chat.getActiveTags(); // ['system', 'startup', 'user']
-```
-
-### 🎯 Instance Scoping
-Multiple chat instances with different styling and behavior:
-
-```javascript
-const salesChat = new quikchat('#sales', handler, {
-    theme: 'quikchat-theme-light',
-    instanceClass: 'sales-chat'
+    // Format content (e.g., markdown → HTML)
+    messageFormatter: (content) => myMarkdownParser(content),
 });
 
-const supportChat = new quikchat('#support', handler, {
-    theme: 'quikchat-theme-dark',
-    instanceClass: 'support-chat'
-});
+// Change at runtime
+chat.setMessageFormatter((content) => marked.parse(content));
+chat.setSanitize((content) => DOMPurify.sanitize(content));
 ```
 
-### 👁 Enhanced Visibility Controls (v1.1.13+)
-Fine-grained control over message display:
-
-```javascript
-// Hide individual messages
-chat.messageSetVisibility(messageId, false);
-
-// Check visibility status
-const isVisible = chat.messageGetVisibility(messageId);
-```
-
-**[View Complete Changelog](https://github.com/deftio/quikchat/releases)**
-
+The pipeline is: **sanitize → format → display**. Sanitize cleans untrusted input; the formatter's output is trusted.
 
+The `-md` and `-md-full` builds pre-wire [quikdown](https://github.com/deftio/quikdown) as the formatter — no configuration needed. The `-md-full` build additionally renders syntax-highlighted code, math equations, Mermaid diagrams, and maps via dynamic CDN loading.
 
-## 🎨 Theming & Customization
+## Theming
 
-QuikChat includes beautiful built-in themes and supports complete customization:
+Themes are pure CSS — colors, borders, and shadows only. The base CSS handles all layout.
 
 ```javascript
-// Use built-in themes
-const chat = new quikchat('#chat', handler, {
-    theme: 'quikchat-theme-dark' // or 'quikchat-theme-light'
-});
-
-// Switch themes dynamically
+// Built-in themes
 chat.changeTheme('quikchat-theme-light');
-```
-
-### Custom Themes
-Create your own themes with CSS:
-
-```css
-.my-custom-theme {
-    border: 2px solid #3b82f6;
-    border-radius: 12px;
-    font-family: 'SF Pro Display', sans-serif;
-}
-
-.my-custom-theme .quikchat-message-content {
-    border-radius: 18px;
-    padding: 12px 16px;
-}
-
-/* Apply to chat */
-const chat = new quikchat('#chat', handler, {
-    theme: 'my-custom-theme'
-});
-```
-
-**📖 [Complete Theming Guide](docs/DEVELOPER-GUIDE.md#theming-guide)**
-
-
+chat.changeTheme('quikchat-theme-dark');
+chat.changeTheme('quikchat-theme-modern');   // chat-bubble style
 
-## 🤖 LLM Integration Examples
-
-### OpenAI Integration
-```javascript
-async function handleMessage(chat, message) {
-    chat.messageAddNew(message, 'You', 'right');
-    
-    const response = await fetch('https://api.openai.com/v1/chat/completions', {
-        method: 'POST',
-        headers: {
-            'Authorization': `Bearer ${API_KEY}`,
-            'Content-Type': 'application/json'
-        },
-        body: JSON.stringify({
-            model: 'gpt-4',
-            messages: formatChatHistory(chat.historyGetAllCopy(), message)
-        })
-    });
-    
-    const data = await response.json();
-    chat.messageAddNew(data.choices[0].message.content, 'Assistant', 'left');
-}
+// Or write your own — just color overrides
 ```
 
-### Streaming Responses
-```javascript
-// Create message for streaming
-const botMsgId = chat.messageAddNew('', 'Bot', 'left');
-
-// Append content as it arrives
-streamingAPI.onChunk(chunk => {
-    chat.messageAppendContent(botMsgId, chunk);
-});
-```
-
-**🛠 [Complete LLM Integration Guide](docs/DEVELOPER-GUIDE.md#llm-integration-best-practices)**
-
-
-
-## 🏗 Framework Integration
-
-### React
-```jsx
-function ChatComponent() {
-    const chatRef = useRef(null);
-    const instanceRef = useRef(null);
-    
-    useEffect(() => {
-        instanceRef.current = new quikchat(chatRef.current, handleMessage);
-    }, []);
-    
-    return <div ref={chatRef} style={{ height: '400px' }} />;
-}
-```
-
-### Vue
-```vue
-<template>
-    <div ref="chatContainer" class="chat-container"></div>
-</template>
-
-<script>
-import quikchat from 'quikchat';
-
-export default {
-    mounted() {
-        this.chat = new quikchat(this.$refs.chatContainer, this.handleMessage);
-    }
+```css
+.my-theme {
+    background-color: #f9f9f9;
+    border: 1px solid #ccc;
+    border-radius: 10px;
 }
-</script>
+.my-theme .quikchat-title-area { color: #333; }
+.my-theme .quikchat-messages-area { background-color: #fff; color: #333; }
+.my-theme .quikchat-input-send-btn { background-color: #4caf50; color: white; border: none; border-radius: 4px; }
 ```
 
-**⚛️ [Framework Integration Examples](docs/DEVELOPER-GUIDE.md#frontend-framework-integration)**
-
-
-
-## 📖 Documentation
-
-| Document | Description |
-|-|-|
-| **[API Reference](docs/API-REFERENCE.md)** | Complete technical reference for all methods and options |
-| **[Developer Guide](docs/DEVELOPER-GUIDE.md)** | Practical recipes and advanced patterns |
-| **[Examples](examples/)** | Working code examples and demos |
-| **[Live Demo](https://deftio.github.io/quikchat/examples/)** | Interactive examples and showcase |
-
-
+The **modern bubble theme** uses alignment classes (`quikchat-align-left`, `quikchat-align-right`) to position messages as chat bubbles with colored backgrounds — left-aligned messages appear as grey bubbles, right-aligned as blue.
 
-## 🌟 Examples & Demos
+Style messages by role with CSS hooks: `.quikchat-role-user`, `.quikchat-role-assistant`, `.quikchat-role-system`, `.quikchat-role-tool`.
 
-- **[Basic Chat](https://deftio.github.io/quikchat/examples/example_umd.html)** - Simple chat interface
-- **[LLM Integration](examples/openai.html)** - OpenAI GPT integration
-- **[Multi-Instance](examples/dual-chatrooms.html)** - Multiple chats on one page
-- **[Visibility Controls](examples/hidden_message.html)** - Message visibility features
-- **[Theme Showcase](https://deftio.github.io/quikchat/examples/)** - Light and dark themes
-- **[React Integration](examples/quikchat-react.html)** - React component example
-- **[Backend Examples](examples/)** - FastAPI and Node.js backends
+## Documentation
 
-**📂 [Browse All Examples](examples/index.html)**
+| Guide | Description |
+|---|---|
+| [Getting Started](docs/getting-started.md) | Installation, minimal example, constructor options |
+| [API Reference](docs/api-reference.md) | Every public method, property, and return value |
+| [Streaming](docs/streaming.md) | Token-by-token LLM response display |
+| [Multi-User Chat](docs/multi-user-chat.md) | Multiple users, dual instances, message routing |
+| [LLM Integration](docs/llm-integration.md) | Ollama, OpenAI, LM Studio, tool calls, conversational memory |
+| [Theming](docs/theming.md) | Custom themes, CSS architecture, built-in themes |
+| [CSS Architecture](docs/css-architecture.md) | Base vs theme separation, ARIA accessibility |
 
+## Demo & Examples
 
+[Live Demo](https://deftio.github.io/quikchat/site/) | [Examples](https://deftio.github.io/quikchat/examples/)
 
-## 🚀 Performance
+Examples include: basic UMD/ESM usage, theme switching, dual chatrooms, markdown rendering ([basic](./examples/example_markdown.html) and [full with syntax highlighting + math + diagrams](./examples/example_md_full.html)), streaming with Ollama/OpenAI/LM Studio, and React integration.
 
-QuikChat is built for production use:
+## Build Variants
 
-- **Lightweight**: ~25KB minified + gzipped
-- **Fast**: Sub-millisecond message rendering
-- **Scalable**: Tested with 10,000 messages rendering in 38ms with virtual scrolling
-- **Memory Efficient**: Only renders visible messages in viewport
+| Build | What you get | Network |
+|---|---|---|
+| **Base** (`quikchat.umd.min.js`) | Chat widget, zero deps | None |
+| **Markdown** (`quikchat-md.umd.min.js`) | + bold, italic, code, tables, lists | None |
+| **Full** (`quikchat-md-full.umd.min.js`) | + syntax highlighting, math, diagrams, maps | CDN on demand |
+| **CSS** (`quikchat.css`) | All 8 themes | None |
 
-**📊 [Virtual Scrolling Technical Details](docs/virtual_scrolling.md) | [Performance Guide](docs/DEVELOPER-GUIDE.md#performance-optimization)**
+All builds are also available in ESM and CJS formats with sourcemaps. See the [downloads page](https://deftio.github.io/quikchat/site/downloads.html) for exact sizes, SRI hashes, and CDN links.
 
+The `-md` builds bundle [quikdown](https://github.com/deftio/quikdown). The `-md-full` build post-processes fence blocks with dynamically loaded renderers (highlight.js, MathJax, Mermaid, Leaflet). The base builds have zero runtime dependencies.
 
-
-## 🛠 Building from Source
+## Building from Source
 
 ```bash
-# Clone repository
-git clone https://github.com/deftio/quikchat.git
-cd quikchat
-
-# Install dependencies
 npm install
-
-# Build for production
-npm run build
-
-# Run tests
-npm test
-
-# Start development server
-npm run dev
+npm run build    # lint, build all formats, report bundle sizes
+npm test         # jest unit tests with coverage
 ```
 
-**Requirements**: Node.js 14+ and npm 6+
-
-
+Build-time tooling (rollup, babel, eslint, jest) is all in devDependencies — zero runtime dependencies.
 
-## 🤝 Contributing
+## Testing
 
-We welcome contributions! Here's how you can help:
-
-1. **🐛 Report Issues** - Found a bug? [Open an issue](https://github.com/deftio/quikchat/issues)
-2. **💡 Feature Requests** - Have an idea? We'd love to hear it
-3. **🔧 Code Contributions** - Submit pull requests for bug fixes or new features
-4. **📖 Documentation** - Help improve our guides and examples
-5. **🌟 Share Examples** - Show us what you've built with QuikChat
-
-### Development Setup
 ```bash
-git clone https://github.com/deftio/quikchat.git
-cd quikchat
-npm install
-npm run dev
+npm test                # unit tests (jest, 100% coverage)
+npm run test:e2e        # browser tests (playwright)
 ```
 
-**📋 [Contributing Guidelines](CONTRIBUTING.md)**
-
+## Development
 
+```bash
+npm run feature my-feature-name        # creates feature/my-feature-name, bumps patch
+npm run feature my-feature-name minor  # bumps minor
+```
 
-## 📄 License
-
-QuikChat is licensed under the [BSD-2-Clause License](LICENSE.txt).
+A pre-commit hook runs lint and tests automatically before each commit.
 
+See [RELEASE-PROCEDURE.md](RELEASE-PROCEDURE.md) for the full release workflow.
 
+## License
 
-## 🔗 Links
+BSD-2-Clause
 
-- **📦 [NPM Package](https://www.npmjs.com/package/quikchat)**
-- **🐙 [GitHub Repository](https://github.com/deftio/quikchat)**
-- **🚀 [Live Examples](https://deftio.github.io/quikchat/examples/)**
-- **📖 [Medium Article](https://medium.com/gitconnected/quikchat-4be8d4a849e5)**
-- **💬 [Issues & Support](https://github.com/deftio/quikchat/issues)**
+## Home Page
 
+[github.com/deftio/quikchat](https://github.com/deftio/quikchat)