@twentyfourg/chat-kit 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 24G
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,222 @@
+# @twentyfourg/chat-kit
+
+A ready-made chat pane for Vue 3 apps that talk to a Base Camp agent.
+
+The Chat component includes the input bar and message list. It handles streaming replies,
+markdown, code blocks and tables, citations (inline popover or a list of source
+cards), thumbs feedback, voice input, and optional math rendering.
+Everything around the chat is yours to build.
+
+All the text and all the colors are settings, so two apps using this can look
+and function completely differently from one another.
+
+## Install
+
+```
+pnpm add @twentyfourg/chat-kit
+```
+
+Vue 3.5 or newer is a peer dependency. Import the theme once, in your app
+entry:
+
+```ts
+import '@twentyfourg/chat-kit/theme.css';
+```
+
+## A working chat
+
+```vue
+<script setup lang="ts">
+import { BaseCampClient, Chat, useChatEngine } from '@twentyfourg/chat-kit';
+
+const transport = new BaseCampClient({
+  baseUrl: import.meta.env.VITE_BASECAMP_API,
+  getAuthToken: () => myAuthToken,
+  deployEnv: import.meta.env.VITE_DEPLOY_ENV,
+  jobNumber: import.meta.env.VITE_JOB_NUMBER,
+});
+
+const engine = useChatEngine({ transport, agentId: import.meta.env.VITE_AGENT_ID });
+</script>
+
+<template>
+  <Chat :engine="engine" />
+</template>
+```
+
+You create the engine, not the component. That way, your other components can interact with the chat from outside of the kit.
+
+`Chat` fills the height it is given and has none of its own, so it needs
+a parent with a real height. There is a worked example in the guide.
+
+## Trying it without a backend
+
+`MockTransport` answers with canned replies over the same streaming path the
+real client uses, so you can build the whole interface before anything is
+wired up.
+
+```ts
+import { MockTransport, useChatEngine } from '@twentyfourg/chat-kit';
+
+const engine = useChatEngine({
+  transport: new MockTransport({ replyTo: () => ({ text: 'Hello.' }) }),
+  agentId: 'agent-1',
+});
+```
+
+## Options
+
+There are two places to set things. How the chat behaves goes on the engine,
+what the chat shows goes on `Chat` as a prop. Everything is optional
+except the transport, the agent id, and the engine itself.
+
+### Engine options
+
+```ts
+const engine = useChatEngine({ transport, agentId, typewriter: { speed: 1.5 } });
+```
+
+| Option | Values | Default | What it does |
+| --- | --- | --- | --- |
+| `typewriter` | `true`, `false`, `{ speed }` | `true` | Reveals the answer a few characters at a time instead of in raw network bursts. `speed: 2` types twice as fast, `0.5` half. |
+| `showMath` | `true`, `false`, `{ fontsDirectory }` | `false` | Runs LaTeX parsing on the answer, so `$...$` and `$$...$$` render as formulas. See [Formulas](#formulas). |
+| `isOutOfScope` | `(text) => boolean` | off | Decides whether a finished answer is the agent declining a question. Those replies get marked and skip the thumbs row. |
+| `onEvent` | `(event) => void` | off | Fires on finished turns, thumbs ratings, and citation clicks. See [Analytics](#analytics). |
+
+### Chat props
+
+```vue
+<Chat :engine="engine" :copy="copy" show-mic show-copy citation-type="list" />
+```
+
+| Prop | Values | Default | What it does |
+| --- | --- | --- | --- |
+| `engine` | the engine | required | The conversation to render. Not a setting. |
+| `copy` | copy map | built-in defaults | Every visible string in the kit. Anything you leave out falls back to its default. |
+| `showMic` | `true`, `false` | `false` | Shows the dictation button, in browsers that support speech recognition. |
+| `citationType` | `'inline'`, `'list'` | `'inline'` | `'inline'` swaps the `[^N]` markers in the answer for numbered chips that open a passage popover. `'list'` drops the markers and shows source cards under the answer instead. |
+| `thinkingVariant` | `'ring'`, `'sparkles'`, `'dots'` | `'ring'` | Which animation plays while the answer is being retrieved. |
+| `rotateThinkingLabel` | `true`, `false` | `false` | Cycles the waiting label through `copy.status.thinkingSequence` instead of holding one line. Set that array to your own list, or to an empty array to turn the cycling off from the copy side. |
+| `showThinking` | `true`, `false` | `false` | Shows the model's reasoning: live while you wait, folded up on the finished reply. |
+| `autoScroll` | `'off'`, `'reply'`, `'bottom'` | `'reply'` | How far the view follows a streaming answer. `'reply'` stops once the answer's own header reaches the top, so a long answer can be read from the beginning. `'bottom'` keeps the newest line in view. `'off'` leaves the view alone. Under `'reply'` and `'bottom'`, scrolling up stops the follow until the reader comes back to the bottom. |
+| `showCopy` | `true`, `false` | `false` | Adds a copy button under each finished answer. |
+
+### Slots
+
+| Slot | What it's for |
+| --- | --- |
+| `welcome` | Replaces the default welcome block that shows before the first message. Use it for a logo, suggested questions, whatever you want. A text-only welcome can just set `copy.welcome` and skip the slot. |
+| `message-actions` | Scoped, gives you `{ message }`. Sits on the left of the row that holds the thumbs, on finished replies. This is where an app's own button goes, an export for example, and it comes before the kit's copy button so your actions stay together. |
+
+### Events
+
+`Chat` emits `rated` with the message and the rating now on it, or `null`
+when the tap cleared it. The kit has already saved the thumb by then, so this is
+for an app that wants to follow up with a form of its own.
+
+```vue
+<Chat :engine="engine" @rated="(message, value) => openFeedbackForm(message, value)" />
+```
+
+## Theming
+
+The components hold no colors, fonts, or spacing of their own. They read CSS
+custom properties, and `theme.css` gives every one of them a plain default so
+the chat is readable in an app that has themed nothing yet.
+
+Override them from your own stylesheet. The defaults are written to lose, so an
+ordinary rule in your app wins wherever the import sits.
+
+Most values point at another value rather than a color, so a rebrand is
+usually five lines:
+
+```css
+:root {
+  --accent: #ffde11;
+  --accent-fg: #000;
+  --text-primary: #fff;
+  --surface-card: #1f2227;
+  --font-body: 'Roboto', sans-serif;
+}
+```
+
+The heading, label, and interface fonts follow `--font-body` unless you set
+them. The citation and button accents follow `--accent`. An app that already
+defines the whole set itself can skip the import.
+
+One thing to watch. If your own tokens live inside a CSS cascade layer, layer
+order decides the winner before anything else does. Import `theme.css` before
+your layered styles, or state the order yourself:
+
+```css
+@layer chat-kit.theme, app;
+```
+
+## Formulas
+
+Answers containing `$...$` or `$$...$$` can be rendered as formulas. This is
+off by default, because a dollar sign is also a currency symbol and prices
+should stay prices.
+
+```
+pnpm add mathlive
+```
+
+```ts
+import 'mathlive/static.css';
+
+const engine = useChatEngine({ transport, agentId, showMath: true });
+```
+
+MathLive is an optional peer dependency. An app that leaves formulas off never
+installs it and never downloads it.
+
+## Analytics
+
+The engine reports completed turns, thumbs ratings, and citation clicks through
+one hook, and your app decides whether any of it gets recorded. The kit never
+sends analytics itself.
+
+```ts
+const engine = useChatEngine({
+  transport,
+  agentId,
+  onEvent: (event) => console.log(event.type, event),
+});
+```
+
+## Full guide
+
+[GUIDE.md](./GUIDE.md) covers every prop, slot, engine option, and copy string,
+plus the layout the chat needs around it and the things it deliberately leaves
+to you.
+
+## House rules
+
+These are what keep the package usable by more than one app.
+
+1. **Nothing about a specific app.** No client names in code, file names, CSS
+   classes, or comments. Anything app-specific arrives through props, engine
+   options, or the copy map.
+2. **No hardcoded visible text.** Components read the `ChatCopy` map, so an app
+   can reword or translate anything.
+3. **No raw colors or fonts.** Styles use the theme's custom properties. Every
+   property a component reads has a default in `theme.css`, and a test fails if
+   one is missing or unused.
+4. **One set of components.** No separate mobile and desktop versions. The
+   layout responds instead.
+5. **Small components.** Around 300 lines each.
+6. **Props down, events up.** No reaching into a child component.
+7. **Backend code stays in `services/`.** Components talk to composables, never
+   to a service. Swapping the backend means writing one transport.
+
+## Working on the kit
+
+```
+pnpm test         # vitest, jsdom
+pnpm type-check
+pnpm lint
+pnpm build        # produces dist/, which is what gets published
+```
+
+Tests run against the source, so no build is needed first.