bunnyquery 1.2.2 → 1.3.0

package/README.md

@@ -6,8 +6,13 @@ account login/signup, conversation history, file & folder uploads, and a setting
 panel — all talking to your project's **BunnyQuery** AI agent.
 
 BunnyQuery is a standalone vanilla-JS port of the BunnyQuery (www.bunnyquery.com) agent
-chatbox. It ships as a single IIFE that exposes `window.BunnyQuery`, plus one
-stylesheet. No build step, no framework, no npm install.
+chatbox. The **widget** ships as a single IIFE that exposes `window.BunnyQuery` plus one
+stylesheet — drop it in via `<script>`, no build step or framework required.
+
+The package also exports the **framework-agnostic chat engine** that powers it
+(`bunnyquery/engine`) — the same DOM-free core the Skapi admin chatbox consumes — so
+you can build your own chat UI on top of it. See
+[Importing the chat engine](#importing-the-chat-engine).
 
 ## Features
 
@@ -68,14 +73,18 @@ call `BunnyQuery.init()`:
 That's it — BunnyQuery takes over the `#chatbox` element and renders the login or
 chat view depending on the user's session.
 
-## Files
+## What's in the package
 
-| File            | Purpose                                                        |
-| --------------- | ------------------------------------------------------------- |
-| `bunnyquery.js`  | The widget. Exposes the global `window.BunnyQuery`.            |
-| `bunnyquery.css` | All styles, scoped under `.bq-agent` / `[data-bq-theme]`.    |
+| Path                          | Purpose                                                                          |
+| ----------------------------- | -------------------------------------------------------------------------------- |
+| `bunnyquery.js`               | The widget IIFE. Exposes the global `window.BunnyQuery`. CDN / `<script>` drop-in. |
+| `bunnyquery.css`              | The widget's full stylesheet, scoped under `.bq-agent` / `[data-bq-theme]`.      |
+| `bunnyquery/engine`           | The framework-agnostic chat engine — ships as ESM + CJS with TypeScript types.   |
+| `bunnyquery/styles/chat.css`  | The shared chat-surface styles (bubbles, markdown, links) for an engine-built UI. |
 
-Host them yourself (same origin recommended) or from a CDN.
+The two widget files can be hosted yourself (same origin recommended) or loaded from a
+CDN — no npm needed. The `engine` / `styles` subpaths are for bundler consumers
+(`npm install bunnyquery`); see [Importing the chat engine](#importing-the-chat-engine).
 
 ## API
 
@@ -138,6 +147,67 @@ To customize colors, override the variables in your own stylesheet **after**
 
 The active theme is saved to `localStorage`, so a returning user keeps their choice.
 
+## Importing the chat engine
+
+`bunnyquery.js` is the ready-made widget. Under it sits a **framework-agnostic,
+DOM-free chat engine** — the same core that powers both this widget and the Skapi
+admin chatbox. Import it from `bunnyquery/engine` when you want to build your own chat
+UI (React, Vue, Svelte, vanilla…) while reusing the engine's message/queue/typewriter/
+cache state machine, request builders, markdown-message composition, and prompts.
+
+Install the package, plus the `skapi-js` SDK (for the transport) and — if you don't
+already have one — a markdown renderer such as `marked`:
+
+```bash
+npm install bunnyquery skapi-js marked
+```
+
+```ts
+import {
+  configureChatEngine,
+  ChatSession,
+  composeUserMessage,
+  type ChatHost,
+} from 'bunnyquery/engine';
+
+// Shared chat-surface styles (message bubbles, rendered markdown, links).
+// Pair it with your own container/layout CSS and the --bq-* design tokens.
+import 'bunnyquery/styles/chat.css';
+
+// 1. Inject the skapi transport + MCP endpoint ONCE at startup.
+configureChatEngine({
+  clientSecretRequest: (opts) => skapi.clientSecretRequest(opts),
+  clientSecretRequestHistory: (params, fetchOptions) =>
+    skapi.clientSecretRequestHistory(params, fetchOptions),
+  mcpBaseUrl: 'https://mcp.broadwayinc.computer',
+  poll: 0, // see the note below
+});
+
+// 2. Implement a ChatHost (identity, render/scroll hooks, the skapi
+//    cancel/refresh surface) for your view, then drive a ChatSession.
+const session = new ChatSession(host); // host: ChatHost
+await session.loadHistory();
+session.dispatchComposedMessage('Hello!'); // send a message
+```
+
+The engine owns chat **state and logic** and calls back into your view through the
+`ChatHost` interface (render, scroll, identity, cancel/refresh). It has **no bundled
+runtime dependencies** — you inject the skapi transport via `configureChatEngine()` and
+render markdown yourself (e.g. with `marked`). Everything is fully typed: `ChatSession`,
+`ChatHost`, `ChatMessage`, `ChatIdentity`, `ChatState`, `composeUserMessage`, the request
+builders (`callClaudeWithPublicMcp` / `callOpenAIWithPublicMcp`, `getChatHistory`,
+`notifyAgentSaveAttachment`), the prompt builders, and the token-budget / link / history
+helpers — see the `.d.ts` shipped with `bunnyquery/engine`.
+
+`configureChatEngine` options:
+
+| Option                        | Type       | Description                                                                                                   |
+| ----------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ |
+| `clientSecretRequest`         | `function` | `skapi.clientSecretRequest`, bound to your Skapi instance. **Required.**                                      |
+| `clientSecretRequestHistory`  | `function` | `skapi.clientSecretRequestHistory`, bound to your Skapi instance. **Required.**                              |
+| `mcpBaseUrl`                  | `string`   | MCP server base URL (you resolve prod vs dev). **Required.**                                                  |
+| `poll`                        | `number?`  | Value attached as `poll` on every request. Omit it if your `clientSecretRequest` already resolves with the final body; pass `0` for the deployed `skapi-js@latest` (needed for the early ack + a manual `.poll()` handle that powers queued-send cancel — the widget's case). |
+
 ## OAuth & redirects
 
 BunnyQuery connects to your AI agent through an MCP OAuth server

package/bunnyquery.css

@@ -1,3 +1,8 @@
+/* GENERATED by scripts/build-css.mjs — DO NOT EDIT.
+ * = src/widget.css (widget chrome + tokens + chat container)
+ * + styles/chat.css (shared chat surface, also bunnyquery/styles/chat.css).
+ * Edit those sources, then run `npm run build`. */
+
 /* ============================================================================
  * BunnyQuery — embeddable AI chat widget
  * Ported from the bunnyquery (www.skapi.com) agent.vue chatbox + login views.
@@ -608,170 +613,13 @@
     font-weight: 600;
 }
 
-/* messages + bubbles */
-.bq-message {
-    display: flex;
-    margin-bottom: 0.5rem;
-}
-.bq-message.is-user { justify-content: flex-end; }
-.bq-message.is-assistant { justify-content: flex-start; }
-
-.bq-bubble {
-    max-width: 85%;
-    padding: 0.55rem 0.7rem;
-    border: 1px solid var(--bq-line);
-    white-space: pre-wrap;
-    line-height: 1.45;
-    font-size: 0.83rem;
-    background: var(--bq-paper);
-}
-.bq-message.is-user .bq-bubble { background: var(--bq-paper); }
-.bq-message.is-assistant:not(.is-error) .bq-bubble {
-    background: var(--bq-success-bg);
-    border-color: var(--bq-success-border);
-}
-.bq-message.is-error .bq-bubble {
-    background: var(--bq-danger-bg);
-    border-color: var(--bq-danger);
-    color: var(--bq-danger);
-}
-.bq-message.is-cancelled .bq-bubble {
-    background: var(--bq-danger-bg);
-    border-color: var(--bq-danger);
-    color: var(--bq-danger);
-    opacity: 0.65;
-}
-.bq-message.is-pending-older .bq-bubble {
-    background: var(--bq-warning-bg);
-    border-color: var(--bq-warning-border);
-    color: var(--bq-warning);
-    transition: opacity 0.25s ease;
-}
-.bq-message.is-sending-to-server .bq-bubble { opacity: 0.4; }
-
-.bq-empty-greeting .bq-bubble {
-    color: var(--bq-muted);
-}
-
-.bq-pending-note {
-    display: block;
-    margin-top: 0.35rem;
-    font-size: 0.7rem;
-    color: var(--bq-warning);
-    font-style: italic;
-}
-.bq-cancel-error {
-    display: block;
-    margin-top: 0.3rem;
-    font-size: 0.68rem;
-    color: var(--bq-danger);
-    font-style: italic;
-    clear: both;
-}
-.bq-cancel-queue-btn {
-    float: right;
-    margin: -0.25rem -0.25rem 0.2rem 0.4rem;
-    width: 1.1rem;
-    height: 1.1rem;
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    padding: 0;
-    border: 1px solid var(--bq-warning-border);
-    background: transparent;
-    color: var(--bq-warning);
-    font-size: 0.85rem;
-    line-height: 1;
-    cursor: pointer;
-    flex-shrink: 0;
-}
-.bq-cancel-queue-btn:hover:not(.is-disabled) { background: var(--bq-warning-bg); }
-.bq-cancel-queue-btn.is-disabled { opacity: 0.3; cursor: not-allowed; pointer-events: none; }
-
-/* in-bubble file/link anchors */
-.bq-file-download,
-.bq-link-button {
-    color: var(--bq-main);
-    text-decoration: none;
-    cursor: pointer;
-    background: transparent;
-    border: 0;
-    padding: 0;
-    font: inherit;
-}
-.bq-file-download:hover,
-.bq-link-button:hover { text-decoration: underline; }
-.bq-link-button {
-    display: inline-block;
-    max-width: 100%;
-    overflow: hidden;
-    text-overflow: ellipsis;
-    white-space: nowrap;
-    vertical-align: bottom;
-}
-
-/* ---- markdown body -------------------------------------------------------*/
-.bq-md { white-space: normal; word-break: break-word; }
-.bq-md > :first-child { margin-top: 0; }
-.bq-md > :last-child { margin-bottom: 0; }
-.bq-md p { margin: 0.4em 0; }
-.bq-md h1 { font-size: 1.3em; }
-.bq-md h2 { font-size: 1.18em; }
-.bq-md h3 { font-size: 1.08em; }
-.bq-md h4, .bq-md h5, .bq-md h6 { font-size: 1em; }
-.bq-md h1, .bq-md h2, .bq-md h3, .bq-md h4, .bq-md h5, .bq-md h6 {
-    margin: 0.8em 0 0.35em;
-    line-height: 1.25;
-    font-weight: 600;
-}
-.bq-md ul, .bq-md ol { margin: 0.4em 0; padding-left: 1.4em; }
-.bq-md li { margin: 0.15em 0; }
-.bq-md blockquote {
-    margin: 0.5em 0;
-    padding: 0.2em 0.8em;
-    border-left: 3px solid var(--bq-line);
-    color: var(--bq-muted);
-    background: rgba(127, 127, 127, 0.08);
-}
-.bq-md hr { border: none; border-top: 1px solid var(--bq-line); margin: 0.8em 0; }
-.bq-md a { color: var(--bq-main); text-decoration: underline; }
-.bq-md a:hover { text-decoration: none; }
-.bq-md code {
-    font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
-    font-size: 0.9em;
-    padding: 0.1em 0.35em;
-    background: rgba(127, 127, 127, 0.16);
-    white-space: pre-wrap;
-    word-break: break-word;
-}
-.bq-md pre {
-    margin: 0.5em 0;
-    padding: 0.6em 0.8em;
-    background: var(--bq-code-bg);
-    color: var(--bq-code-fg);
-    overflow-x: auto;
-    white-space: pre;
-}
-.bq-md pre code {
-    background: transparent;
-    color: inherit;
-    padding: 0;
-    font-size: 0.85em;
-    word-break: normal;
-}
-.bq-md table {
-    border-collapse: collapse;
-    margin: 0.5em 0;
-    font-size: 0.95em;
-    display: block;
-    overflow-x: auto;
-}
-.bq-md th, .bq-md td { border: 1px solid var(--bq-line); padding: 0.3em 0.55em; text-align: left; }
-.bq-md th { background: rgba(127, 127, 127, 0.1); font-weight: 600; }
-.bq-md img { max-width: 100%; height: auto; border-radius: 4px; }
-.bq-md strong { font-weight: 600; }
-.bq-md em { font-style: italic; }
-.bq-md del { text-decoration: line-through; }
+/* messages + bubbles: the CORE conversation styling (bubble padding/colors,
+   rendered markdown, in-bubble link anchors, queue/cancel affordances) is
+   authored ONCE in @skapi/chat-engine/styles/chat.css and concatenated onto
+   this file by the build (scripts/build-css.mjs). Only the widget-specific
+   container bits stay here. */
+.bq-bubble { max-width: 85%; }
+.bq-empty-greeting .bq-bubble { color: var(--bq-muted); }
 
 /* ---- composer / input row ------------------------------------------------*/
 .bq-input-row {
@@ -860,7 +708,8 @@
     position: absolute;
     inset: 0 auto 0 0;
     width: var(--att-progress, 0%);
-    background: rgba(240, 98, 146, 0.18);
+    /* theme-reactive tint (matches agent.vue's fade()→color-mix() change) */
+    background: color-mix(in srgb, var(--bq-main) 18%, transparent);
     transition: width 0.15s linear;
     z-index: 0;
     pointer-events: none;
@@ -996,6 +845,19 @@
     color: var(--bq-paper);
 }
 
+/* "apply to all remaining files" checkbox in the overwrite/reindex prompt */
+.bq-overwrite-applyall {
+    display: flex;
+    align-items: center;
+    gap: 0.4rem;
+    margin: -0.5rem 0 1.25rem;
+    font-size: 0.82rem;
+    color: var(--bq-ink);
+    cursor: pointer;
+    user-select: none;
+}
+.bq-overwrite-applyall input { cursor: pointer; margin: 0; }
+
 /* ============================================================================
  * RESPONSIVE
  * ==========================================================================*/
@@ -1015,3 +877,198 @@
 .bq-modal-root[data-bq-theme="dark"] .bq-icon-invertible {
     filter: invert(var(--bq-icon-invert));
 }
+
+/**
+ * @skapi/chat-engine — shared chat-display styles.
+ *
+ * The conversation surface (message bubbles, rendered markdown, in-bubble file/
+ * link anchors, the queue/cancel affordances) must look IDENTICAL in agent.vue
+ * (the Vue admin chatbox) and the BunnyQuery widget. These rules are authored
+ * ONCE here and consumed by both:
+ *   - agent.vue imports this file as a NON-scoped <style> block (so the rules
+ *     also reach the v-html `.bq-md` markdown, which has no scope attribute).
+ *   - the widget concatenates it into the shipped bunnyquery.css at build time.
+ *
+ * Each consumer supplies the `--bq-*` design tokens (light + dark) and keeps its
+ * OWN container/layout rules — `.bq-chat`, `.bq-messages` padding, the
+ * `.bq-history-loading` treatment, the empty-greeting, and the bubble max-width
+ * — which legitimately differ between an embedded admin panel and a standalone
+ * widget. Colors here are theme-reactive (tokens + rgba(127,127,127,…) neutral
+ * transparency) so the surface works in both light and dark schemes.
+ *
+ * Token contract (the consumer must define these): --bq-paper, --bq-line,
+ * --bq-muted, --bq-main, --bq-success-bg, --bq-success-border, --bq-danger,
+ * --bq-danger-bg, --bq-warning, --bq-warning-bg, --bq-warning-border,
+ * --bq-code-bg, --bq-code-fg.
+ */
+
+/* ---- messages + bubbles --------------------------------------------------*/
+.bq-message { display: flex; margin-bottom: 0.5rem; }
+.bq-message.is-user { justify-content: flex-end; }
+.bq-message.is-assistant { justify-content: flex-start; }
+
+.bq-bubble {
+    padding: 0.55rem 0.7rem;
+    border: 1px solid var(--bq-line);
+    white-space: pre-wrap;
+    line-height: 1.45;
+    font-size: 0.83rem;
+    background: var(--bq-paper);
+}
+.bq-bubble span { word-break: break-word; }
+.bq-message.is-user .bq-bubble { background: var(--bq-paper); }
+.bq-message.is-assistant:not(.is-error) .bq-bubble {
+    background: var(--bq-success-bg);
+    border-color: var(--bq-success-border);
+}
+.bq-message.is-error .bq-bubble {
+    background: var(--bq-danger-bg);
+    border-color: var(--bq-danger);
+    color: var(--bq-danger);
+}
+.bq-message.is-cancelled .bq-bubble {
+    background: var(--bq-danger-bg);
+    border-color: var(--bq-danger);
+    color: var(--bq-danger);
+    opacity: 0.65;
+}
+.bq-message.is-pending-older .bq-bubble {
+    background: var(--bq-warning-bg);
+    border-color: var(--bq-warning-border);
+    color: var(--bq-warning);
+    transition: opacity 0.25s ease;
+}
+.bq-message.is-sending-to-server .bq-bubble { opacity: 0.4; }
+
+/* ---- queue / cancel affordances -----------------------------------------*/
+.bq-pending-note {
+    display: block;
+    margin-top: 0.35rem;
+    font-size: 0.7rem;
+    color: var(--bq-warning);
+    font-style: italic;
+}
+.bq-cancel-error {
+    display: block;
+    margin-top: 0.3rem;
+    font-size: 0.68rem;
+    color: var(--bq-danger);
+    font-style: italic;
+    clear: both;
+}
+.bq-cancel-queue-btn {
+    float: right;
+    margin: -0.25rem -0.25rem 0.2rem 0.4rem;
+    width: 1.1rem;
+    height: 1.1rem;
+    min-height: 0;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    padding: 0;
+    border: 1px solid var(--bq-warning-border);
+    background: transparent;
+    color: var(--bq-warning);
+    font-size: 0.85rem;
+    line-height: 1;
+    cursor: pointer;
+    box-shadow: none;
+    border-radius: 0;
+    flex-shrink: 0;
+}
+.bq-cancel-queue-btn:hover:not(.is-disabled) { background: var(--bq-warning-bg); color: var(--bq-warning); }
+.bq-cancel-queue-btn.is-disabled { opacity: 0.3; cursor: not-allowed; pointer-events: none; }
+
+/* ---- in-bubble file / link anchors --------------------------------------*/
+.bq-file-download,
+.bq-link-button {
+    color: var(--bq-main);
+    text-decoration: none;
+    cursor: pointer;
+    background: transparent;
+    border: 0;
+    padding: 0;
+    font: inherit;
+}
+.bq-file-download:hover,
+.bq-link-button:hover { color: var(--bq-main); text-decoration: underline; background: transparent; }
+.bq-link-button {
+    display: inline-block;
+    max-width: 100%;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    vertical-align: bottom;
+}
+/* While the temporary URL is being re-resolved the click is swallowed — show a
+   busy cursor and dim it so it reads as "working, don't click again". */
+.bq-link-button.is-refreshing { cursor: progress; opacity: 0.6; }
+
+/* ---- rendered-markdown body ----------------------------------------------*/
+/* Overrides the bubble's `white-space: pre-wrap` since marked already produces
+   structural HTML; pre/code reinstate pre-wrap for their own content. */
+.bq-md { white-space: normal; word-break: break-word; }
+.bq-md > :first-child { margin-top: 0; }
+.bq-md > :last-child { margin-bottom: 0; }
+.bq-md p { margin: 0.4em 0; }
+.bq-md h1 { font-size: 1.3em; }
+.bq-md h2 { font-size: 1.18em; }
+.bq-md h3 { font-size: 1.08em; }
+.bq-md h4, .bq-md h5, .bq-md h6 { font-size: 1em; }
+.bq-md h1, .bq-md h2, .bq-md h3, .bq-md h4, .bq-md h5, .bq-md h6 {
+    margin: 0.8em 0 0.35em;
+    line-height: 1.25;
+    font-weight: 600;
+}
+.bq-md ul, .bq-md ol { margin: 0.4em 0; padding-left: 1.4em; }
+.bq-md li { margin: 0.15em 0; }
+.bq-md li > p { margin: 0.2em 0; }
+.bq-md blockquote {
+    margin: 0.5em 0;
+    padding: 0.2em 0.8em;
+    border-left: 3px solid var(--bq-line);
+    color: var(--bq-muted);
+    background: rgba(127, 127, 127, 0.08);
+}
+.bq-md hr { border: none; border-top: 1px solid var(--bq-line); margin: 0.8em 0; }
+.bq-md a { color: var(--bq-main); text-decoration: underline; }
+.bq-md a:hover { text-decoration: none; }
+.bq-md code {
+    font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    font-size: 0.9em;
+    padding: 0.1em 0.35em;
+    background: rgba(127, 127, 127, 0.16);
+    border-radius: 0;
+    white-space: pre-wrap;
+    word-break: break-word;
+}
+.bq-md pre {
+    margin: 0.5em 0;
+    padding: 0.6em 0.8em;
+    background: var(--bq-code-bg);
+    color: var(--bq-code-fg);
+    border-radius: 0;
+    overflow-x: auto;
+    white-space: pre;
+}
+.bq-md pre code {
+    background: transparent;
+    color: inherit;
+    padding: 0;
+    font-size: 0.85em;
+    white-space: pre;
+    word-break: normal;
+}
+.bq-md table {
+    border-collapse: collapse;
+    margin: 0.5em 0;
+    font-size: 0.95em;
+    display: block;
+    overflow-x: auto;
+}
+.bq-md th, .bq-md td { border: 1px solid var(--bq-line); padding: 0.3em 0.55em; text-align: left; }
+.bq-md th { background: rgba(127, 127, 127, 0.1); font-weight: 600; }
+.bq-md img { max-width: 100%; height: auto; border-radius: 4px; }
+.bq-md strong { font-weight: 600; }
+.bq-md em { font-style: italic; }
+.bq-md del { text-decoration: line-through; }