@rohansguliani/mux-chat-ui 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rohan Guliani
+
+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,83 @@
+# @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.
+
+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"
+
+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",
+  onToolResult: ({ readOnly }) => { if (!readOnly) refreshTodos() },
+})
+
+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`.
+
+## Testing your app
+
+`@rohansguliani/mux-chat-ui/testing` gives app tests stable hooks, so they
+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.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
+```

package/dist/controller.d.ts

@@ -0,0 +1,66 @@
+import { type ChatSessionView, type ChatState, type PermissionRequest, type QuestionRequest, type Turn } from "@rohansguliani/mux-chat-core";
+import { type ModelGroup } from "./model.js";
+export type { ChatGrant, ChatTool } from "@rohansguliani/mux-chat-core";
+/**
+ * A tool call that finished while the chat was open. `readOnly` comes from
+ * the app's tool definitions (built-in tools such as web search are read-only),
+ * so `!readOnly` means the call may have changed app data.
+ */
+export type ToolResult = {
+    tool: string;
+    title?: string;
+    input: Record<string, unknown>;
+    output: string;
+    sessionID: string;
+    readOnly: boolean;
+};
+export type ControllerOptions = {
+    /** Where the app mounts `mux.handle`. */
+    url: string;
+    agent: string;
+    sessionTitle: string;
+    storageKey: string;
+    preferredModel?: string;
+    onToolResult?: (result: ToolResult) => void;
+};
+export type Status = {
+    tone: "ok" | "busy" | "bad";
+    text: string;
+};
+/**
+ * What happened to a message: delivered; shown but unconfirmed (it stays in
+ * the transcript and `retry()` completes it); or not delivered at all, so the
+ * caller still owns the text.
+ */
+export type SendResult = "sent" | "unconfirmed" | "failed";
+export declare function createChatController(options: ControllerOptions): {
+    /** Changes once per rendered frame while the transcript updates. */
+    changes: import("solid-js").Accessor<ChatState>;
+    sessionID: import("solid-js").Accessor<string | undefined>;
+    /** Labels from the app's tool definitions. */
+    toolLabels: () => Record<string, string>;
+    messageIDs: import("solid-js").Accessor<string[]>;
+    turn: (id: string) => Turn | undefined;
+    questions: import("solid-js").Accessor<readonly QuestionRequest[]>;
+    permissions: import("solid-js").Accessor<readonly PermissionRequest[]>;
+    streaming: import("solid-js").Accessor<boolean>;
+    ready: () => boolean;
+    view: import("solid-js").Accessor<ChatSessionView>;
+    status: import("solid-js").Accessor<Status>;
+    error: () => string;
+    /** A message is shown but its delivery was not confirmed; `retry()` completes it. */
+    unconfirmed: () => boolean;
+    modelGroups: import("solid-js").Accessor<ModelGroup[]>;
+    modelValue: import("solid-js").Accessor<string>;
+    selectModel: (value: string) => void;
+    send(text: string): Promise<SendResult>;
+    retry(): Promise<void>;
+    abort: () => Promise<void>;
+    answer: (requestID: string, answers: string[][]) => Promise<void>;
+    reject: (requestID: string) => Promise<void>;
+    replyPermission: (requestID: string, response: "once" | "always" | "reject") => Promise<void>;
+    /** Loads the next older page of history, if any. */
+    older: () => void;
+    newChat(): Promise<void>;
+};
+export type ChatController = ReturnType<typeof createChatController>;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { mountMuxChat, MuxChat, type MuxChatHandle, type MuxChatOptions } from "./mount.jsx";
+export type { ChatGrant, ToolResult } from "./controller.js";