@mlx-bun/module-chat 0.0.0-stage → 1.0.0

package/src/panel/dom.ts

@@ -0,0 +1,94 @@
+// The small DOM and network helpers the panel's files share. A panel imports only its own files, so these are
+// its own; they follow the host page's conventions (a `#toasts` container, the `.toast` classes) documented in
+// the module's README.
+import type { ApiEnvelope } from "../protocol";
+
+export const $ = (id: string): HTMLElement => document.getElementById(id) as HTMLElement;
+
+/** Build a DOM node quickly. */
+export function el<K extends keyof HTMLElementTagNameMap>(tag: K, cls?: string, parent?: Element | null): HTMLElementTagNameMap[K] {
+  const e = document.createElement(tag);
+  if (cls) e.className = cls;
+  if (parent) parent.appendChild(e);
+  return e;
+}
+
+/** Toast notification in the host's `#toasts` container (a host without one shows none). kind: "" | "ok" | "err". */
+export function toast(msg: string, kind = "", ms = 4200): void {
+  const container = document.getElementById("toasts");
+  if (!container) return;
+  const t = el("div", "toast " + kind, container);
+  t.textContent = msg;
+  setTimeout(() => { t.style.transition = "opacity .4s,transform .4s"; t.style.opacity = "0"; t.style.transform = "translateY(10px)"; setTimeout(() => t.remove(), 420); }, ms);
+}
+
+const injectedStyleIds = new Set<string>();
+
+/** Append a `<style>` block to `<head>` exactly once per `id`. */
+export function injectStyles(id: string, css: string): void {
+  if (injectedStyleIds.has(id)) return;
+  injectedStyleIds.add(id);
+  const style = document.createElement("style");
+  style.id = id;
+  style.textContent = css;
+  document.head.appendChild(style);
+}
+
+/** A focus trap for a popover or drawer: Tab and Shift+Tab cycle within the container while `isOpen()` is true, and
+ * focus returns to whatever triggered it when it closes. */
+export interface FocusTrap {
+  /** Call right before opening: remembers the trigger to restore focus to. */
+  capture(): void;
+  /** Call right after closing. */
+  restore(): void;
+}
+
+export function trapFocus(container: HTMLElement, isOpen: () => boolean): FocusTrap {
+  let lastFocused: HTMLElement | null = null;
+  const focusables = (): HTMLElement[] => [...container.querySelectorAll(
+    'a[href],button:not([disabled]),textarea,input:not([disabled]),select,[tabindex]:not([tabindex="-1"])'
+  )].filter((e) => (e as HTMLElement).offsetParent !== null || e === document.activeElement) as HTMLElement[];
+  container.addEventListener("keydown", (e) => {
+    const ke = e as KeyboardEvent;
+    if (ke.key !== "Tab" || !isOpen()) return;
+    const items = focusables();
+    if (!items.length) return;
+    const first = items[0]!, last = items[items.length - 1]!;
+    if (ke.shiftKey && document.activeElement === first) { ke.preventDefault(); last.focus(); }
+    else if (!ke.shiftKey && document.activeElement === last) { ke.preventDefault(); first.focus(); }
+  });
+  return {
+    capture() { lastFocused = document.activeElement as HTMLElement | null; },
+    restore() { if (lastFocused && lastFocused.focus) lastFocused.focus(); lastFocused = null; },
+  };
+}
+
+/** The page the address names among the sections the host page mounted; an empty or unknown address is the chat. */
+export function currentRoute(): string {
+  const route = (location.hash || "").replace(/^#\/?/, "").split("?")[0] || "";
+  return [...document.querySelectorAll<HTMLElement>("section[data-route]")].some(section => section.dataset.route === route) ? route : "chat";
+}
+
+export type ApiOpts = (Omit<RequestInit, "body"> & { body?: unknown }) | undefined;
+
+/** Fetch JSON with graceful error handling. Throws only on transport failure: an HTTP failure is reflected in the
+ * returned envelope, so callers can always `await api(...)`. OpenAI-envelope errors (`{error:{message}}`) are
+ * unwrapped to a plain string. */
+export async function api<T extends ApiEnvelope = ApiEnvelope>(path: string, opts?: ApiOpts): Promise<T> {
+  const { body, ...rest } = opts || {};
+  const init: RequestInit = {
+    headers: { "content-type": "application/json" },
+    ...rest,
+    ...(body !== undefined ? { body: typeof body === "string" ? body : JSON.stringify(body) } : {}),
+  };
+  const r = await fetch(path, init);
+  const text = await r.text();
+  let data: ApiEnvelope;
+  try { data = text ? JSON.parse(text) : {}; } catch { data = { ok: false, error: text.slice(0, 400) || ("HTTP " + r.status) }; }
+  if (data && data.error && typeof data.error === "object") {
+    const errObj = data.error as { message?: string };
+    data.error = errObj.message || JSON.stringify(errObj).slice(0, 400);
+  }
+  if (!r.ok && data.ok === undefined) data = { ok: false, error: (data.error as string) || data.message || ("HTTP " + r.status) };
+  return data as T;
+}

package/src/panel/host.ts

@@ -0,0 +1,28 @@
+// What the panel takes from the page that hosts it, beyond its connection. Everything is optional: a host
+// with none gets a chat that stands alone (no memory chips, no settings section). The shell sets it as the
+// element's `host` property before the panel attaches.
+
+/** A tool card a host draws in place of the default one (memory's provenance chip). */
+export interface ToolCardHandle {
+  /** The card's element, already appended to the bubble it was given. */
+  readonly wrap: HTMLElement;
+  /** Called with the tool's streamed and final results. */
+  setResult(result: unknown): void;
+}
+
+export interface ChatHost {
+  /** Called once the panel's markup exists and its controls are wired: the host attaches what lives beside the chat (the
+   * memory entry in the sidebar, the first-run consent card) and keeps the element for its own calls. */
+  mounted?(panel: HTMLElement): void;
+  /** Draws a tool call in place of the default card; null leaves it to the panel. */
+  toolCard?(parent: HTMLElement, tool: string, args: unknown): ToolCardHandle | null;
+  /** The agent-tools section of the host's settings dialog. */
+  settings?: {
+    /** The browser's saved wish for file-changing tools (re-asserted on every connection). */
+    codingToolsPreference(): boolean;
+    /** The server's report: `active` is what this chat was built with, `pending` the request that applies to the next one. */
+    codingTools(active: boolean, pending: boolean): void;
+    /** The always-allow list, with the action that forgets one entry. */
+    approvals(tools: readonly string[], forget: (tool: string) => void): void;
+  };
+}

package/src/panel/index.ts

@@ -0,0 +1,100 @@
+// `<mlx-chat-panel>`: the chat as a workspace panel. It is the product's own page, so the shell gives it the whole
+// page, keeps it attached while another page shows (a turn in flight and the socket survive a visit elsewhere) and
+// tells it when its page is shown (`enter`) and hidden (`leave`). It renders into the light DOM, with its own
+// markup and stylesheet, and takes only its host's design tokens; what lives beside it on the host page (memory's
+// sidebar entry, the settings dialog's agent-tools section) is wired through the `host` property (`ChatHost`).
+// The panel talks to the module's socket (`/ws/chat`) and routes (`/api/sessions/*`, `/api/settings/tool-approvals`),
+// which keep their shipped paths.
+import { createChatController } from "./chat";
+import { exportSession, openSessionRowByPath } from "./sessions";
+import { $, injectStyles, trapFocus, type FocusTrap } from "./dom";
+import type { ChatHost } from "./host";
+import { closeTopPopover, hasOpenPopover } from "./popovers";
+import { STYLE } from "./style";
+import { MARKUP } from "./template";
+
+export type { ChatHost, ToolCardHandle } from "./host";
+
+// Importing the entry outside a browser (package verification, a server-side inventory) loads without defining the element.
+const Base: typeof HTMLElement = (globalThis as { HTMLElement?: typeof HTMLElement }).HTMLElement ?? (class {} as unknown as typeof HTMLElement);
+
+class ChatPanel extends Base {
+  /** Set by the shell before the panel attaches; unused (the module's routes keep their shipped paths). */
+  connection: unknown;
+  host: ChatHost | undefined;
+  #controller: ReturnType<typeof createChatController> | undefined;
+  #drawer: FocusTrap | undefined;
+
+  connectedCallback() {
+    if (this.#controller) return;
+    injectStyles("mlx-chat-panel-style", STYLE);
+    this.innerHTML = MARKUP;
+    const sidebar = $("chat-sidebar");
+    this.#drawer = trapFocus(sidebar, () => sidebar.classList.contains("drawer-open"));
+    $("chat-drawer-backdrop").addEventListener("click", () => this.closeDrawer());
+    this.#controller = createChatController({
+      host: this.host, element: this,
+      isActive: () => !!this.closest("section")?.classList.contains("active"),
+      closeDrawer: () => this.closeDrawer(),
+    });
+    this.#controller.init();
+  }
+
+  /** The chat page is shown: connect if the socket is down, focus the composer, refresh the adapter list. */
+  enter() { this.#controller?.enter(); }
+  /** The chat page is hidden: the socket stays up, since closing it would drop a turn in flight. */
+  leave() { this.#controller?.leave(); }
+
+  /** Start a fresh chat (the old one stays on disk). */
+  newChat() { (this.#controller?.newChat as (() => void) | undefined)?.(); }
+  /** Copy the last assistant response, as its own Copy button does. */
+  copyLastResponse() { (this.#controller?.copyLastResponse as (() => void) | undefined)?.(); }
+  /** Ask for (or stop asking for) file-changing tools; applies from the next new, opened or forked chat. */
+  setCodingTools(enabled: boolean) { this.#controller?.setCodingTools(enabled); }
+  /** Reload the adapter list (a training job finished). */
+  refreshAdapters() { this.#controller?.refreshAdapters(); }
+  focusComposer() { $("chat-box")?.focus(); }
+  /** Toggle the model's reasoning, as its pill does. */
+  toggleThinking() { $("chat-think")?.click(); }
+
+  /** The recent chats the sidebar lists (or filters), for the host's palette. */
+  recentChats(): { title: string; path: string }[] {
+    return [...document.querySelectorAll<HTMLElement>("#chat-sessions .sess")].flatMap(row =>
+      row.dataset.path ? [{ title: row.querySelector(".stitle")?.textContent || "New chat", path: row.dataset.path }] : []);
+  }
+  /** Open a recent chat by its file path, as clicking its row does; false when the sidebar does not list it. */
+  openSession(path: string): boolean { return openSessionRowByPath(path); }
+  /** Download the chat the sidebar marks active (Markdown by default); nothing when there is none. */
+  async exportActiveChat(format: "md" | "json" = "md"): Promise<void> {
+    const row = document.querySelector<HTMLElement>("#chat-sessions .sess.active");
+    if (!row || !row.dataset.path) return;
+    await exportSession(row.dataset.path, row.querySelector(".stitle")?.textContent || "chat", format);
+  }
+
+  /** The mobile drawer: the recent-chats sidebar as a slide-over. */
+  toggleDrawer() { $("chat-sidebar").classList.contains("drawer-open") ? this.closeDrawer() : this.openDrawer(); }
+  openDrawer() {
+    if (!this.#drawer) return;
+    this.#drawer.capture();
+    $("chat-sidebar").classList.add("drawer-open");
+    $("chat-drawer-backdrop").classList.add("open");
+    this.#drawerTrigger()?.setAttribute("aria-expanded", "true");
+    setTimeout(() => { const search = $("chat-sess-search"); if (search) search.focus(); }, 30);
+  }
+  closeDrawer() {
+    if (!this.#drawer) return;
+    $("chat-sidebar").classList.remove("drawer-open");
+    $("chat-drawer-backdrop").classList.remove("open");
+    this.#drawerTrigger()?.setAttribute("aria-expanded", "false");
+    this.#drawer.restore();
+  }
+  drawerOpen(): boolean { return !!this.#drawer && $("chat-sidebar").classList.contains("drawer-open"); }
+  /** The host's control that opens the drawer, if it has one (it names the sidebar in `aria-controls`). */
+  #drawerTrigger(): Element | null { return document.querySelector('[aria-controls="chat-sidebar"]'); }
+
+  /** The popovers (sampling, system prompt, adapter table) for the host's Escape sweep. */
+  popoverOpen(): boolean { return hasOpenPopover(); }
+  closePopover(): boolean { return closeTopPopover(); }
+}
+
+if (typeof customElements !== "undefined" && !customElements.get("mlx-chat-panel")) customElements.define("mlx-chat-panel", ChatPanel);