bunnyquery 1.8.3 → 1.8.5

package/README.md

@@ -1,28 +1,28 @@
 # BunnyQuery
 
 An embeddable, dependency-free AI chat widget for [Skapi](https://www.skapi.com)-powered
-projects. Drop it into any web page and your users get a full chat experience —
+projects. Drop it into any web page and your users get a full chat experience:
 account login/signup, conversation history, file & folder uploads, and a settings
-panel — all talking to your project's **BunnyQuery** AI agent.
+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. 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.
+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
+(`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
 
 - **AI chat** against your project's configured agent (Claude or OpenAI under the
-  hood), with streaming-style "Thinking…" indicators and a background indexing queue.
-- **Authentication** — email/password login, optional signup, password change,
+  hood), with animated pending indicators and a background indexing queue.
+- **Authentication**: email/password login, optional signup, password change,
   email verification, account recovery, and "Sign in with Google".
-- **Conversation history** — paginated, with "Fetching history…" indicators on
+- **Conversation history**: paginated, with "Fetching history…" indicators on
   first load and on scroll-up.
-- **Attachments** — drag-and-drop files and folders, per-file upload status
+- **Attachments**: drag-and-drop files and folders, per-file upload status
   (uploading / failed / indexed), overflow collapsing for large batches, and a
   prompt when an upload hits a file that already exists (skip / reindex only /
   overwrite, with "apply to all remaining"). Images are read with vision/OCR,
@@ -33,12 +33,12 @@ you can build your own chat UI on top of it. See
   across as many passes as it takes. A file's passes collapse into a single
   status row in the chat that can be expanded, and stopped: "Stop" cancels every
   queued and running pass at once and ends the continuation chain.
-- **Attachment parser plugins** — register a client-side parser so the widget
+- **Attachment parser plugins**: register a client-side parser so the widget
   extracts text in the browser from formats the model can't otherwise read, and
   indexes it directly. See [Attachment parser plugins](#attachment-parser-plugins).
-- **Settings panel** — in-place inside the chat: light/dark theme, account details,
+- **Settings panel**, in place inside the chat: light/dark theme, account details,
   newsletter subscription, clear history, and remove account.
-- **Theming** — light and dark modes via CSS custom properties; the choice is
+- **Theming**: light and dark modes via CSS custom properties; the choice is
   remembered in `localStorage` and falls back to the OS preference.
 
 ## Requirements
@@ -82,7 +82,7 @@ call `BunnyQuery.init()`:
 </html>
 ```
 
-That's it — BunnyQuery takes over the `#chatbox` element and renders the login or
+That's it. BunnyQuery takes over the `#chatbox` element and renders the login or
 chat view depending on the user's session.
 
 ## What's in the package
@@ -91,11 +91,11 @@ chat view depending on the user's session.
 | ----------------------------- | -------------------------------------------------------------------------------- |
 | `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/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. |
 
 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
+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
@@ -123,6 +123,7 @@ Mounts the widget. Returns the `BunnyQuery` object.
 | `mcpBaseUrl`             | `string`  | `null`   | Override the MCP OAuth server base URL entirely (advanced).                                   |
 | `hostDomain`             | `string`  | `null`   | db-CDN host for temporary file URLs. Defaults to `skapi.app` (dev) / `skapi.com` (prod).     |
 | `attachmentParsers`      | `array`   | `null`   | Client-side attachment parsers. See [Attachment parser plugins](#attachment-parser-plugins). |
+| `windowedIndexing`       | `boolean` | `true`   | Server-driven windowed indexing for text and grid files (see [file types](#supported-file-types)). Pass `false` to fall back to agent-driven paging, which keeps the traversal inside the model's turn budget and the tab open. |
 
 ### Methods
 
@@ -142,9 +143,9 @@ BunnyQuery.toggleTheme();
 BunnyQuery.logout();
 ```
 
-> `init()` is idempotent — calling it twice logs a warning and returns the existing
+> `init()` is idempotent: calling it twice logs a warning and returns the existing
 > instance rather than re-mounting. On a successful mount it logs its version, e.g.
-> `[bunnyquery] v1.7.0`.
+> `[bunnyquery] v1.8.3`.
 
 See [HISTORY.md](HISTORY.md) for the release-by-release changelog.
 
@@ -209,13 +210,13 @@ upload: a 5MB `.txt` indexed 4.0% of its content, a 4.8MB `.json` 4.2%, a
 because the agent received a plausible-looking document with no way to know most
 of it was missing.
 
-Two drivers exist for this loop. By default the agent pages the file itself with
-the `readFileContent` tool. With the engine's `windowedIndexing` option enabled,
+Two drivers exist for this loop. With `windowedIndexing` (the widget's default)
 the **worker** reads a window per request and continues from the reader's own
-cursor, so the traversal no longer has to fit inside the model's turn budget.
-That option is off by default and must only be turned on against a deployed
-worker (see [Importing the chat engine](#importing-the-chat-engine)); the widget
-does not enable it.
+cursor, so the traversal neither has to fit inside the model's turn budget nor
+depends on the tab staying open. Without it the agent pages the file itself with
+the `readFileContent` tool. Pass `windowedIndexing: false` to `init()` to opt
+out; engine consumers opt in via `configureChatEngine` (see
+[Importing the chat engine](#importing-the-chat-engine)).
 
 ### 4. Everything else extractable: inlined as text server-side
 
@@ -223,8 +224,10 @@ The skapi proxy downloads the file, extracts its text **server-side**, and
 inlines that text into the request, so the model reads it directly with no
 fetching. This keeps indexing consistent across model providers.
 
-**Office & e-book** (binary/zip, parsed):
-`.docx` · `.xlsx` · `.pptx` · `.hwp` · `.hwpx` · `.ods` · `.odt` · `.odp` · `.epub`
+**Office & e-book** (binary/zip, parsed; includes legacy binary `.doc`/`.xls`/`.ppt`
+and the macro-enabled `.docm`/`.xlsm`/`.pptm`):
+`.doc` · `.docx` · `.docm` · `.xls` · `.xlsx` · `.xlsm` · `.ppt` · `.pptx` · `.pptm`
+· `.hwp` · `.hwpx` · `.ods` · `.odt` · `.odp` · `.epub`
 
 **Text, data, markup & source code** (decoded as text; `.html`/`.htm` have their
 tags stripped):
@@ -261,13 +264,9 @@ via `web_search` (external web access is enabled).
 
 ### Caveats
 
-- **Legacy / macro Office** — `.doc` `.xls` `.ppt` (legacy binary) and `.docm`
-  `.xlsm` `.pptm` (macro-enabled) have no reliable server-side reader. They
-  upload fine but are indexed from **metadata only**; re-save as
-  `.docx` / `.xlsx` / `.pptx` (or PDF) to capture their contents.
-- **Anything else** — a format covered by none of the above is indexed from its
+- **Anything else**: a format covered by none of the above is indexed from its
   metadata. To support it, register your own
-  [Attachment parser plugin](#attachment-parser-plugins) — it runs in the browser
+  [Attachment parser plugin](#attachment-parser-plugins), which runs in the browser
   and feeds parsed text straight into indexing.
 
 ### Re-indexing an existing file
@@ -311,7 +310,7 @@ interface AttachmentParser {
 ```
 
 The first parser whose `match` returns `true` wins. A parser that throws or
-returns nothing is ignored — the file falls back to its normal path. Output is
+returns nothing is ignored, and the file falls back to its normal path. Output is
 capped (~200k chars) before it is inlined.
 
 ### Example
@@ -370,13 +369,13 @@ The active theme is saved to `localStorage`, so a returning user keeps their cho
 ## 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
+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`:
+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
@@ -412,12 +411,12 @@ 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
+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`.
+helpers. See the `.d.ts` shipped with `bunnyquery/engine`.
 
 `configureChatEngine` options:
 
@@ -426,9 +425,9 @@ helpers — see the `.d.ts` shipped with `bunnyquery/engine`.
 | `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). |
+| `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). |
 | `attachmentParsers`           | `array?`   | Client-side attachment parsers, registered at configure time. More can be added later with `registerAttachmentParser()`. See [Attachment parser plugins](#attachment-parser-plugins). |
-| `windowedIndexing`            | `boolean?` | Opt in to **server-driven** windowed indexing for text and grid files (see [file types](#supported-file-types)). Off by default and must stay off until the worker that strips the `_skapi_window` directive is deployed: against an older worker the directive reaches the provider as an unknown body field and the call fails terminally with no retry. |
+| `windowedIndexing`            | `boolean?` | Opt in to **server-driven** windowed indexing for text and grid files (see [file types](#supported-file-types)). Off by default in the engine; the widget passes it as `true`. The deployed skapi workers support it; only leave it off against a self-hosted worker that does not yet strip the `_skapi_window` directive, where it would reach the provider as an unknown body field and fail the call terminally with no retry. |
 
 ### Display and paging helpers
 
@@ -464,7 +463,7 @@ never progress.
 BunnyQuery connects to your AI agent through an MCP OAuth server
 (`mcp.broadwayinc.computer` in production, `mcp-dev.broadwayinc.computer` when
 `dev: true`). After authorization, the OAuth server redirects back to **the current
-host page** — BunnyQuery reads the `?code=…&state=…` parameters, completes the
+host page**: BunnyQuery reads the `?code=…&state=…` parameters, completes the
 exchange, and cleans them from the URL automatically. No dedicated callback page is
 needed; just make sure the page that hosts the widget is a stable, reachable URL.
 

package/bunnyquery.css

@@ -1119,7 +1119,17 @@
     border: 1px solid var(--bq-line);
     background: rgba(127, 127, 127, 0.05);
 }
+/* Three states, three colours, and the row is readable at a glance without
+   opening it:
+     yellow  working on it now      (.is-active)
+     green   indexed, confirmed     (.is-indexed)
+     grey    not known yet          (.is-resolving, and the base look)
+   Grey is the DEFAULT rather than a colour of its own, so anything that has not
+   earned green or yellow reads as "no claim" — which is also what a cancelled
+   row should look like, and what an unrecognised future state would fall back
+   to. Red stays reserved for a failure. */
 .bq-index-group.is-active { border-color: var(--bq-warning-border); background: var(--bq-warning-bg); }
+.bq-index-group.is-indexed { border-color: var(--bq-success-border); background: var(--bq-success-bg); }
 .bq-index-group.is-error { border-color: var(--bq-danger); background: var(--bq-danger-bg); }
 
 .bq-index-head {
@@ -1142,7 +1152,12 @@
 }
 .bq-index-head:hover { background: rgba(127, 127, 127, 0.08); color: var(--bq-muted); }
 .bq-index-group.is-active .bq-index-head { color: var(--bq-warning); }
+.bq-index-group.is-indexed .bq-index-head { color: var(--bq-success); }
 .bq-index-group.is-error .bq-index-head { color: var(--bq-danger); }
+/* Stated rather than inherited: a waiting row keeping the muted default is a
+   DECISION (it is not claiming a state), not an oversight, and writing it here
+   means adding a colour to the base rule cannot silently give it one. */
+.bq-index-group.is-resolving .bq-index-head { color: var(--bq-muted); }
 
 /* Status glyph. The active one is a circular-arrow SVG the consumer inlines
    (never an icon font: agent.vue's Material Symbols build gates glyphs behind
@@ -1158,8 +1173,17 @@
 .bq-index-icon svg { width: 100%; height: 100%; display: block; }
 .bq-index-group.is-active .bq-index-icon svg { animation: bq-index-spin 1.1s linear infinite; }
 @keyframes bq-index-spin { to { transform: rotate(360deg); } }
+/* Waiting to find out (a run whose earlier passes are still being paged in, a
+   file whose queue state has not been answered). Deliberately NOT the active
+   look: no warning colour and no spin, because a spinning glyph on a chat row is
+   read as "this file is being worked on right now" and that is the one thing this
+   state does not know. A slow fade says "pending" without claiming progress. */
+.bq-index-group.is-resolving .bq-index-icon svg { animation: bq-index-fade 1.6s ease-in-out infinite; }
+@keyframes bq-index-fade { 0%, 100% { opacity: 1; } 50% { opacity: 0.35; } }
 @media (prefers-reduced-motion: reduce) {
     .bq-index-group.is-active .bq-index-icon svg { animation-duration: 3s; }
+    /* A fade has no end state to settle on, so it stops rather than slows. */
+    .bq-index-group.is-resolving .bq-index-icon svg { animation: none; opacity: 0.7; }
 }
 
 .bq-index-label {
@@ -1218,8 +1242,28 @@
     border-left: 2px solid var(--bq-line);
 }
 .bq-message.bq-index-pass .bq-bubble { font-size: 0.78rem; }
-/* Close the run: the next ordinary message needs its normal breathing room. */
-.bq-message.bq-index-pass + :not(.bq-index-pass) { margin-top: 0.55rem; }
+/* Close the run: the next ordinary message needs its normal breathing room.
+   NOT scoped to .bq-message: the trailing loader below is a run member too, and
+   requiring .bq-message would silently drop the gap whenever it is the last one. */
+.bq-index-pass + :not(.bq-index-pass) { margin-top: 0.55rem; }
+/* Trailing loader: an open row keeps a "still working" mark of its own for as long
+   as the file's indexing is not confirmed over. It sits on the same rail as the
+   passes so it reads as the run continuing rather than as a message of its own —
+   which is why the rail is repeated here instead of reusing the rule above, whose
+   selector requires .bq-message. */
+.bq-index-tail {
+    margin-bottom: 0.3rem;
+    margin-left: 0.7rem;
+    padding: 0.1rem 0 0.1rem 0.7rem;
+    border-left: 2px solid var(--bq-line);
+    font-size: 0.78rem;
+    color: var(--bq-muted);
+}
+/* An open row animates for as long as the file is indexing, which can be minutes.
+   Readers who ask for less motion get the static end state. */
+@media (prefers-reduced-motion: reduce) {
+    .bq-index-tail .bq-loader::after { animation: none; content: '...'; }
+}
 .bq-index-note {
     padding: 0 0.6rem 0.45rem;
     font-size: 0.7rem;
@@ -1253,6 +1297,68 @@
 /* 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; }
+/* The client asked for a url for this file and did not get one, so the chip is
+   emitted with NO href (it cannot navigate) and with ✕ in place of ↗. Paint it
+   as the dead text it now is: muted, no underline, default cursor, and no hover
+   response, since the base rule above still fires on hover and would otherwise
+   promising a link. */
+.bq-link-button.is-unavailable,
+.bq-link-button.is-unavailable:hover {
+    color: var(--bq-muted);
+    text-decoration: none;
+    cursor: default;
+}
+
+/* ---- inline image previews ----------------------------------------------*/
+/* The anchor IS the preview: picture on top, the ordinary chip underneath as a
+   caption. The caption is the FALLBACK, not decoration: when the url dies or the
+   file is gone the <img> hides itself and what is left is exactly the text chip
+   this feature replaced, still clickable. */
+.bq-link-button.is-image-preview {
+    display: inline-block;
+    max-width: 100%;
+    white-space: normal;
+    overflow: visible;
+    text-overflow: clip;
+    vertical-align: top;
+    margin: 0.25em 0;
+}
+/* Qualified with .bq-md because `.bq-md img` below already sets max-width and
+   would otherwise out-specify a bare .bq-img-preview. */
+.bq-md img.bq-img-preview {
+    display: block;
+    /* Bounded on BOTH axes so a 12000px panorama and a 40x9000 sliver each land
+       inside the bubble; width/height auto keep the aspect ratio. The bubble cap
+       differs per client, so the preview carries its own. */
+    max-width: min(100%, 320px);
+    max-height: 320px;
+    width: auto;
+    height: auto;
+    border-radius: 4px;
+    border: 1px solid var(--bq-line);
+    /* A transparent PNG is invisible on paper without this. */
+    background: rgba(127, 127, 127, 0.08);
+}
+/* Keyed on the MISSING src, not on a state class: the element is emitted with no
+   src at all (the url has to be minted first) and a src-less <img> would
+   otherwise paint the browser's broken-image glyph. */
+.bq-md img.bq-img-preview:not([src]),
+.bq-md img.bq-img-preview[data-bq-img-state="error"] { display: none; }
+/* The dot trail covers the mint round trip, then gets out of the way. */
+.bq-md img.bq-img-preview[src] ~ [data-bq-img-loader],
+.bq-md img.bq-img-preview[data-bq-img-state="error"] ~ [data-bq-img-loader] { display: none; }
+.bq-img-preview-caption {
+    display: inline-block;
+    max-width: 100%;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    vertical-align: bottom;
+}
+/* A collapsed indexing row is a single line and its label is the indexed file's
+   own path, which is frequently an image. Never grow that row into a picture. */
+.bq-index-label .bq-md img.bq-img-preview,
+.bq-index-label [data-bq-img-loader] { display: none; }
 
 /* ---- rendered-markdown body ----------------------------------------------*/
 /* Overrides the bubble's `white-space: pre-wrap` since marked already produces