@rohansguliani/mux-chat-ui 0.3.0 → 0.4.0

package/README.md

@@ -1,59 +1,61 @@
 # @rohansguliani/mux-chat-ui
 
-Mux's chat as a drop-in panel for your app: the streaming transcript, tool
-activity rows, reasoning, question cards, the model picker, Stop, and New chat.
-It renders with Mux's own stylesheets (synced from Mux, see below) inside a
-shadow root, so it looks like Mux and neither affects nor inherits your page's
-CSS.
+Mux's own chat as pieces you lay out in your app: the conversation, the
+composer, the model and reasoning menus, and a ready-made panel. They are
+Mux's actual components (built from the Mux commit the runtime package pins),
+styled from their own stylesheet, scoped so they never restyle your page.
 
 Your server mounts one route with
 [`@rohansguliani/mux-chat-runtime`](https://www.npmjs.com/package/@rohansguliani/mux-chat-runtime):
 `app.all("/api/mux/*", (c) => mux.handle(c.req.raw, { subject: userID }))`.
 
-```ts
-import { mountMuxChat } from "@rohansguliani/mux-chat-ui"
+```tsx
+import { createMuxChat, MuxChat, MuxTranscript, MuxComposer, MuxModelPicker } from "@rohansguliani/mux-chat-ui"
+import "@rohansguliani/mux-chat-ui/style.css"
 
-const chat = mountMuxChat(document.getElementById("assistant")!, {
-  title: "Assistant",
-  subtitle: "Reads and edits your todos",
-  suggestions: [{ label: "What's due today?", prompt: "What is due today?" }],
-  theme: "dark",
+const chat = createMuxChat({
+  storageKey: "todos",
   onToolResult: ({ readOnly }) => { if (!readOnly) refreshTodos() },
 })
 
+<MuxChat chat={chat} colorScheme="dark" tokens={{ "background-base": "#0f1114", "text-interactive-base": "#8ab4ff" }}>
+  <header class="my-header">Assistant <MuxModelPicker /> <button onClick={() => chat.newChat()}>New chat</button></header>
+  <MuxTranscript empty={<MyStarterPrompts onPick={(text) => chat.send(text)} />} />
+  <MuxComposer placeholder="Ask about your todos…" pickers={false} />
+</MuxChat>
+
 chat.send("Summarize my week")   // e.g. from a button elsewhere in your app
 ```
 
-Tool rows use each tool's `label` from your tool definitions, and
-`onToolResult` reports `readOnly` from them too, so the app never lists its
-tools again on the client.
-
-Give the host element a height (a sidebar column); the chat fills it. In a
-Solid app, `<MuxChat {...options} class="sidebar" ref={(handle) => ...} />`
-does the same.
-
-| Option | Default | |
-| --- | --- | --- |
-| `url` | `/api/mux` | where the app mounts `mux.handle` |
-| `title`, `subtitle`, `placeholder` | `Assistant` | header and empty state |
-| `suggestions` | none | starter prompts in an empty chat |
-| `toolLabels` | each tool's `label` | overrides names in the transcript |
-| `preferredModel` | runtime default | `provider/model`, until the user picks one |
-| `onToolResult` | | a tool call finished while the chat was open; `readOnly: false` means it may have changed app data |
-| `theme` | follows the OS | `light` or `dark` |
-| `storageKey` | `mux-chat` | prefix for the remembered chat and model (localStorage) |
-
-It resumes the user's last chat on reload, keeps its grant renewed (retrying
-through outages), reconnects the stream, and pages older history as you scroll
-up (all through [`@rohansguliani/mux-chat-core`](https://www.npmjs.com/package/@rohansguliani/mux-chat-core)). A message the
-server refuses (for example over a per-user limit) goes back into the
-composer; one whose delivery is unconfirmed stays in the transcript with a
-Retry button. Questions and permission requests from the assistant appear
-above the composer. `chat.send()` from your page waits until the chat is
-ready.
-
-`solid-js` is a peer dependency (npm installs it); apps on other frameworks
-only call `mountMuxChat`.
+| Piece | |
+| --- | --- |
+| `createMuxChat(options)` | the signed-in user's chat: grant (renewed before it expires), their last chat or a new one, `send`, `newChat`, `retry`, `focus`, `dispose` |
+| `<MuxChat chat colorScheme tokens class style>` | the root the pieces sit in; your own elements can sit in it too |
+| `<MuxTranscript empty>` | the conversation, with its loading, failed, and ended states |
+| `<MuxComposer placeholder pickers>` | the composer, or the assistant's open question or permission request |
+| `<MuxModelPicker>`, `<MuxReasoningPicker>` | the menus, wherever you want them |
+| `<MuxChatPanel title subtitle placeholder suggestions>` | a ready-made layout of all of the above |
+| `mountMuxChat(element, options)` | the ready-made panel for apps not written in Solid |
+
+`createMuxChat` options: `url` (where `mux.handle` is mounted, default
+`/api/mux`), `storageKey`, `sessionTitle`, `preferredModel` (`provider/model`
+until the user picks one), `toolLabels` (default: each tool's `label`), and
+`onToolResult` (a tool call finished while the chat was open; `readOnly:
+false` means it may have changed app data).
+
+**Styling.** `tokens` sets Mux's theme values (names without `--`), e.g.
+`background-base`, `background-stronger`, `surface-raised-base`,
+`text-strong`, `text-base`, `text-weak`, `border-weak-base`,
+`text-interactive-base`, `font-family-sans`. Your own CSS can target the
+pieces' `data-component`/`data-action` attributes too; Mux's rules sit in
+cascade layers (`mux-*`), so unlayered app rules win. Every Mux rule is scoped
+to the pieces' root (the build fails otherwise), and menus render in an
+overlay root that carries the same theme.
+
+**Bundling.** `solid-js` is a peer dependency (one Solid for the app and the
+pieces). The markdown and diff workers are ES-module workers: with Vite, set
+`worker: { format: "es" }`. Code highlighting, math, and diagrams load on
+demand.
 
 ## Testing your app
 
@@ -63,21 +65,11 @@ never depend on the chat's markup:
 ```js
 import { chatSelectors, readChat, replyFinished } from "@rohansguliani/mux-chat-ui/testing"
 
-await page.fill(chatSelectors.input, "Add NVDA to Tech")   // selectors pierce the shadow root in Playwright
+await page.locator(`#assistant ${chatSelectors.input}`).fill("Add NVDA to Tech")
 await page.keyboard.press("Enter")
 await page.waitForFunction(replyFinished, await page.$("#assistant"))
 const { replies, tools, sessionID } = await page.locator("#assistant").evaluate(readChat)
 ```
 
-## Styles
-
-`src/styles/mux/` holds Mux's stylesheets (theme tokens, markdown, tool rows,
-collapsible, shimmer, dock surfaces, message parts), copied by a script that
-rewrites `:root` to `:host` and makes the dark palette selectable. The
-components render the markup those stylesheets target. `src/styles/chat.css`
-adds the embed layout and the few composer rules Mux writes as Tailwind
-classes. After Mux's styles change:
-
-```bash
-MUX_SOURCE=../mux npm run sync-styles
-```
+To pin a model in tests, set `${storageKey}:model` in localStorage to
+`provider/model` before starting a new chat.

package/dist/testing.d.ts

@@ -1,25 +1,28 @@
+/** Selectors for the chat's pieces on the page. */
 export declare const chatSelectors: {
+    /** The `<MuxChat>` root. */
+    readonly root: "[data-component=\"mux-chat\"]";
     /** The event stream is connected. */
-    readonly connected: "[data-slot=\"mux-chat-status\"][data-tone=\"ok\"]";
+    readonly connected: "[data-component=\"mux-chat\"][data-connected]";
     /** The chat can take a message. */
     readonly ready: "[data-component=\"prompt-composer-surface\"][aria-busy=\"false\"]";
     readonly input: "[data-component=\"prompt-input\"]";
     readonly submit: "[data-action=\"prompt-submit\"]";
     /** The submit button while a reply streams (clicking stops it). */
     readonly stop: "[data-action=\"prompt-submit\"][data-working]";
+    /** Opens the model menu. */
     readonly model: "[data-action=\"prompt-model\"]";
     readonly newChat: "[data-action=\"new-chat\"]";
     readonly retry: "[data-action=\"retry\"]";
+    readonly suggestion: "[data-action=\"suggestion\"]";
     readonly userMessage: "[data-component=\"user-message\"]";
-    readonly reply: "[data-component=\"assistant-message\"] [data-component=\"text-part\"]";
-    /** Reply text while it is still streaming. */
-    readonly liveReply: "[data-component=\"assistant-message\"][data-live] [data-component=\"text-part\"]";
-    readonly tool: "[data-component=\"assistant-message\"] .tool-collapsible[data-status]";
-    readonly question: "[data-component=\"mux-question\"]";
-    readonly questionOption: "[data-slot=\"mux-question-option\"]";
-    readonly questionAnswer: "[data-component=\"mux-question\"] [data-slot=\"mux-button\"][data-variant=\"primary\"]";
-    readonly permission: "[data-component=\"mux-permission\"]";
-    readonly notice: "[data-slot=\"mux-chat-notice\"]";
+    readonly reply: "[data-component=\"session-turn\"] [data-component=\"text-part\"] [data-component=\"markdown\"]";
+    readonly tool: ".tool-collapsible[data-status]";
+    readonly question: "[data-component=\"dock-prompt\"][data-kind=\"question\"]";
+    readonly questionOption: "[data-slot=\"question-option\"]";
+    /** Submits the chosen answer (the last footer button). */
+    readonly questionAnswer: "[data-slot=\"question-footer-actions\"] button:last-child";
+    readonly permission: "[data-component=\"dock-prompt\"][data-kind=\"permission\"]";
 };
 export type ChatSnapshot = {
     /** The open chat session, once there is one. */
@@ -28,6 +31,8 @@ export type ChatSnapshot = {
     connected: boolean;
     /** A reply is streaming. */
     busy: boolean;
+    /** The selected model's name. */
+    model: string;
     userMessages: string[];
     replies: string[];
     tools: Array<{
@@ -40,10 +45,9 @@ export type ChatSnapshot = {
         options: string[];
     } | null;
     permission: string | null;
-    notice: string;
     errors: string[];
 };
-/** What the chat mounted in `host` shows right now. */
+/** What the chat in `host` (its `<MuxChat>` root or an ancestor) shows right now. */
 export declare function readChat(host: Element): ChatSnapshot;
-/** True once the chat mounted in `host` has a reply and nothing is streaming. */
+/** True once the chat in `host` has rendered a reply and nothing is streaming. */
 export declare function replyFinished(host: Element): boolean;

package/dist/testing.js

@@ -1,61 +1,75 @@
-//#region src/testing.ts
-var chatSelectors = {
-	/** The event stream is connected. */
-	connected: "[data-slot=\"mux-chat-status\"][data-tone=\"ok\"]",
-	/** The chat can take a message. */
-	ready: "[data-component=\"prompt-composer-surface\"][aria-busy=\"false\"]",
-	input: "[data-component=\"prompt-input\"]",
-	submit: "[data-action=\"prompt-submit\"]",
-	/** The submit button while a reply streams (clicking stops it). */
-	stop: "[data-action=\"prompt-submit\"][data-working]",
-	model: "[data-action=\"prompt-model\"]",
-	newChat: "[data-action=\"new-chat\"]",
-	retry: "[data-action=\"retry\"]",
-	userMessage: "[data-component=\"user-message\"]",
-	reply: "[data-component=\"assistant-message\"] [data-component=\"text-part\"]",
-	/** Reply text while it is still streaming. */
-	liveReply: "[data-component=\"assistant-message\"][data-live] [data-component=\"text-part\"]",
-	tool: "[data-component=\"assistant-message\"] .tool-collapsible[data-status]",
-	question: "[data-component=\"mux-question\"]",
-	questionOption: "[data-slot=\"mux-question-option\"]",
-	questionAnswer: "[data-component=\"mux-question\"] [data-slot=\"mux-button\"][data-variant=\"primary\"]",
-	permission: "[data-component=\"mux-permission\"]",
-	notice: "[data-slot=\"mux-chat-notice\"]"
+// Stable hooks into a rendered chat for app tests (Playwright, Puppeteer, DOM
+// tests), so apps never depend on the chat's markup. `chatSelectors` work on
+// the page (the pieces render in it). `readChat` and `replyFinished` take the
+// `<MuxChat>` root or any element containing it; pass them to
+// `locator.evaluate` / `page.waitForFunction`. They are self-contained for
+// that reason.
+/** Selectors for the chat's pieces on the page. */
+export const chatSelectors = {
+    /** The `<MuxChat>` root. */
+    root: '[data-component="mux-chat"]',
+    /** The event stream is connected. */
+    connected: '[data-component="mux-chat"][data-connected]',
+    /** The chat can take a message. */
+    ready: '[data-component="prompt-composer-surface"][aria-busy="false"]',
+    input: '[data-component="prompt-input"]',
+    submit: '[data-action="prompt-submit"]',
+    /** The submit button while a reply streams (clicking stops it). */
+    stop: '[data-action="prompt-submit"][data-working]',
+    /** Opens the model menu. */
+    model: '[data-action="prompt-model"]',
+    newChat: '[data-action="new-chat"]',
+    retry: '[data-action="retry"]',
+    suggestion: '[data-action="suggestion"]',
+    userMessage: '[data-component="user-message"]',
+    reply: '[data-component="session-turn"] [data-component="text-part"] [data-component="markdown"]',
+    tool: '.tool-collapsible[data-status]',
+    question: '[data-component="dock-prompt"][data-kind="question"]',
+    questionOption: '[data-slot="question-option"]',
+    /** Submits the chosen answer (the last footer button). */
+    questionAnswer: '[data-slot="question-footer-actions"] button:last-child',
+    permission: '[data-component="dock-prompt"][data-kind="permission"]',
 };
-/** What the chat mounted in `host` shows right now. */
-function readChat(host) {
-	const root = host.shadowRoot ?? host;
-	const one = (selector) => root.querySelector(selector);
-	const all = (selector) => [...root.querySelectorAll(selector)];
-	const text = (element) => element?.textContent ?? "";
-	const question = one("[data-component=\"mux-question\"]");
-	return {
-		sessionID: one("[data-component=\"mux-chat\"]")?.getAttribute("data-session-id") || null,
-		ready: !!one("[data-component=\"prompt-composer-surface\"][aria-busy=\"false\"]"),
-		connected: !!one("[data-slot=\"mux-chat-status\"][data-tone=\"ok\"]"),
-		busy: !!one("[data-component=\"assistant-message\"][data-live]") || !!one("[data-action=\"prompt-submit\"][data-working]"),
-		userMessages: all("[data-component=\"user-message\"] [data-slot=\"user-message-text\"]").map(text),
-		replies: all("[data-component=\"assistant-message\"] [data-component=\"text-part\"]").map(text),
-		tools: all("[data-component=\"assistant-message\"] .tool-collapsible[data-status]").map((row) => ({
-			status: row.getAttribute("data-status") ?? "",
-			label: row.querySelector("[data-slot=\"basic-tool-tool-title\"] [data-component=\"text-shimmer\"]")?.getAttribute("aria-label") ?? "",
-			detail: text(row.querySelector("[data-slot=\"basic-tool-tool-subtitle\"]"))
-		})),
-		question: question ? {
-			text: text(question.querySelector("[data-slot=\"mux-question-text\"]")),
-			options: [...question.querySelectorAll("[data-slot=\"mux-question-option-label\"]")].map(text)
-		} : null,
-		permission: text(one("[data-component=\"mux-permission\"] [data-slot=\"mux-question-text\"]")) || null,
-		notice: text(one("[data-slot=\"mux-chat-notice\"]")),
-		errors: all("[data-slot=\"mux-chat-error\"]").map(text)
-	};
+/** What the chat in `host` (its `<MuxChat>` root or an ancestor) shows right now. */
+export function readChat(host) {
+    const root = host.matches('[data-component="mux-chat"]') ? host : host.querySelector('[data-component="mux-chat"]');
+    const one = (selector) => root?.querySelector(selector) ?? null;
+    const all = (selector) => (root ? [...root.querySelectorAll(selector)] : []);
+    const text = (element) => (element?.textContent ?? "").trim();
+    const question = one('[data-component="dock-prompt"][data-kind="question"]');
+    return {
+        sessionID: root?.getAttribute("data-session-id") || null,
+        ready: !!one('[data-component="prompt-composer-surface"][aria-busy="false"]'),
+        connected: !!root?.hasAttribute("data-connected"),
+        busy: !!one('[data-action="prompt-submit"][data-working]'),
+        model: text(one('[data-action="prompt-model"]')),
+        userMessages: all('[data-component="user-message"] [data-slot="user-message-text"]').map(text),
+        // The rendered reply only, without the part's copy and model/timing row.
+        replies: all('[data-component="session-turn"] [data-component="text-part"] [data-component="markdown"]').map(text),
+        tools: all(".tool-collapsible[data-status]").map((row) => {
+            const title = row.querySelector('[data-slot="basic-tool-tool-title"]');
+            return {
+                status: row.getAttribute("data-status") ?? "",
+                label: title?.querySelector("[aria-label]")?.getAttribute("aria-label") ?? text(title),
+                detail: text(row.querySelector('[data-slot="basic-tool-tool-subtitle"]')),
+            };
+        }),
+        question: question
+            ? {
+                text: text(question.querySelector('[data-slot="question-text"]')),
+                options: [...question.querySelectorAll('[data-slot="question-option"] [data-slot="option-label"]')].map(text),
+            }
+            : null,
+        permission: text(one('[data-component="dock-prompt"][data-kind="permission"] [data-slot="permission-hint"]')) || null,
+        errors: all('[role="alert"]').map(text).filter(Boolean),
+    };
 }
-/** True once the chat mounted in `host` has a reply and nothing is streaming. */
-function replyFinished(host) {
-	const root = host.shadowRoot ?? host;
-	return !root.querySelector("[data-component=\"assistant-message\"][data-live]") && !root.querySelector("[data-action=\"prompt-submit\"][data-working]") && !!root.querySelector("[data-component=\"assistant-message\"] [data-component=\"text-part\"]");
+/** True once the chat in `host` has rendered a reply and nothing is streaming. */
+export function replyFinished(host) {
+    const root = host.matches('[data-component="mux-chat"]') ? host : host.querySelector('[data-component="mux-chat"]');
+    if (!root || root.querySelector('[data-action="prompt-submit"][data-working]'))
+        return false;
+    // Markdown renders after its part appears; wait for the text itself.
+    const replies = root.querySelectorAll('[data-component="session-turn"] [data-component="text-part"] [data-component="markdown"]');
+    return !!replies[replies.length - 1]?.textContent?.trim();
 }
-//#endregion
-export { chatSelectors, readChat, replyFinished };
-
-//# sourceMappingURL=testing.js.map