@dogsbay/plugin-ask 0.2.0-beta.81

package/README.md

@@ -0,0 +1,45 @@
+# @dogsbay/plugin-ask
+
+A floating "Ask AI" button for Dogsbay docs sites. It opens a modal, sends the
+question to a configured backend, and shows the answer — so a static docs site
+can offer AI search without shipping any secrets.
+
+## Install
+
+```bash
+pnpm add @dogsbay/plugin-ask
+```
+
+## Use
+
+```yaml
+# dogsbay.config.yml
+plugins:
+  - name: "@dogsbay/plugin-ask"
+    options:
+      endpoint: "https://<your-ask-endpoint>"
+      site: "openshift-docs-dogsbay"
+```
+
+`endpoint` and `site` are required; everything else is presentation.
+
+## Options
+
+| Option | Required | Default | Description |
+|---|---|---|---|
+| `endpoint` | yes | — | URL of the backend the widget calls. |
+| `site` | yes | — | Site id sent with each request to select the corpus. |
+| `mode` | no | `answer` | `answer` (generated answer) or `search` (results). |
+| `buttonLabel` | no | `Ask AI` | Floating button text. |
+| `title` | no | `Ask the docs` | Modal heading. |
+| `placeholder` | no | `Ask a question…` | Input placeholder. |
+| `position` | no | `bottom-right` | `bottom-right` or `bottom-left`. |
+
+## Styling
+
+Styles use Dogsbay theme tokens with fallbacks; override the `.dba-*` classes to
+customize.
+
+## License
+
+MIT.

package/dist/client.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":""}

package/dist/client.js

@@ -0,0 +1,124 @@
+/**
+ * Client runtime for `@dogsbay/plugin-ask`.
+ *
+ * Imported via the auto-generated `src/lib/plugin-runtime.ts` in the user's
+ * Astro project, so it runs for side effects on every page. It injects a
+ * floating button + <dialog> at <body> level (outside the article), and on
+ * submit streams an answer from the dogsbay-ask proxy.
+ *
+ * Astro view transitions: the document is swapped on navigation, so we mount
+ * on `astro:page-load` and tear down on `astro:before-swap` to avoid stale
+ * nodes / duplicate buttons.
+ */
+// @ts-expect-error: virtual module resolved by the Dogsbay Vite alias at build.
+import config from "virtual:dogsbay-plugin-config/@dogsbay/plugin-ask";
+import { buildAskRequest, extractText } from "./protocol.js";
+const cfg = config;
+const ROOT_ID = "dba-root";
+function mount() {
+    if (typeof document === "undefined")
+        return;
+    if (document.getElementById(ROOT_ID))
+        return; // already mounted
+    const root = document.createElement("div");
+    root.id = ROOT_ID;
+    root.dataset.position = cfg.position;
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className = "dba-trigger";
+    button.textContent = cfg.buttonLabel;
+    button.setAttribute("aria-haspopup", "dialog");
+    const dialog = document.createElement("dialog");
+    dialog.className = "dba-dialog";
+    dialog.setAttribute("aria-label", cfg.title);
+    dialog.innerHTML = `
+    <form class="dba-form" method="dialog">
+      <header class="dba-header">
+        <h2 class="dba-title"></h2>
+        <button type="button" class="dba-close" aria-label="Close">×</button>
+      </header>
+      <div class="dba-inputrow">
+        <input class="dba-input" type="text" autocomplete="off" enterkeyhint="search" />
+        <button type="submit" class="dba-submit">Ask</button>
+      </div>
+      <div class="dba-answer" aria-live="polite" tabindex="-1"></div>
+    </form>
+  `;
+    // textContent (not innerHTML) for user-configurable strings — no injection.
+    dialog.querySelector(".dba-title").textContent = cfg.title;
+    const input = dialog.querySelector(".dba-input");
+    input.placeholder = cfg.placeholder;
+    const answer = dialog.querySelector(".dba-answer");
+    const form = dialog.querySelector(".dba-form");
+    const submit = dialog.querySelector(".dba-submit");
+    button.addEventListener("click", () => {
+        dialog.showModal();
+        input.focus();
+    });
+    dialog.querySelector(".dba-close").addEventListener("click", () => dialog.close());
+    form.addEventListener("submit", async (e) => {
+        e.preventDefault();
+        const query = input.value.trim();
+        if (!query)
+            return;
+        submit.disabled = true;
+        answer.dataset.state = "loading";
+        answer.textContent = "…";
+        try {
+            const res = await fetch(cfg.endpoint, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(buildAskRequest(cfg.site, query, cfg.mode)),
+            });
+            if (!res.ok || !res.body) {
+                throw new Error(`Request failed (${res.status})`);
+            }
+            answer.textContent = "";
+            answer.dataset.state = "streaming";
+            const reader = res.body.getReader();
+            const decoder = new TextDecoder();
+            let buf = "";
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                buf += decoder.decode(value, { stream: true });
+                // Only process complete lines; keep any partial line buffered so a
+                // `data:` frame split across reads isn't parsed half-formed.
+                const nl = buf.lastIndexOf("\n");
+                if (nl >= 0) {
+                    answer.textContent += extractText(buf.slice(0, nl + 1));
+                    buf = buf.slice(nl + 1);
+                }
+            }
+            if (buf)
+                answer.textContent += extractText(buf);
+            answer.dataset.state = "done";
+        }
+        catch (err) {
+            answer.dataset.state = "error";
+            answer.textContent = `Sorry — something went wrong. ${err.message}`;
+        }
+        finally {
+            submit.disabled = false;
+        }
+    });
+    root.append(button, dialog);
+    document.body.appendChild(root);
+}
+function unmount() {
+    if (typeof document === "undefined")
+        return;
+    document.getElementById(ROOT_ID)?.remove();
+}
+if (typeof document !== "undefined") {
+    if (document.readyState === "loading") {
+        document.addEventListener("DOMContentLoaded", mount);
+    }
+    else {
+        mount();
+    }
+    document.addEventListener("astro:page-load", mount);
+    document.addEventListener("astro:before-swap", unmount);
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import type { DogsbayPlugin } from "@dogsbay/types";
+import { type AskOptions } from "./schema.js";
+export type { AskOptions } from "./schema.js";
+export default function ask(input?: AskOptions): DogsbayPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAS5D,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,CAAC,OAAO,UAAU,GAAG,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,aAAa,CA4B7D"}

package/dist/index.js

@@ -0,0 +1,53 @@
+/**
+ * `@dogsbay/plugin-ask` — adds a floating "Ask AI" widget to every page of a
+ * Dogsbay docs site. The widget POSTs the user's question to a shared
+ * dogsbay-ask proxy (a Cloudflare Worker over AI Search) and streams back a
+ * grounded answer. No build-time content transform — purely a client module +
+ * styles + a build-time→client config bridge.
+ *
+ * Usage:
+ *
+ *   # dogsbay.config.yml
+ *   plugins:
+ *     - name: "@dogsbay/plugin-ask"
+ *       options:
+ *         endpoint: "https://dogsbay-ask.<subdomain>.workers.dev"
+ *         site: "openshift-docs-dogsbay"
+ *
+ * The `endpoint` + `site` are required; everything else is presentation.
+ */
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseOptions } from "./schema.js";
+// __dirname is `dist/` for the published package. Client JS is built next to
+// this file; styles ship un-built at the package root under `src/`.
+const PLUGIN_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.resolve(PLUGIN_DIR, "..");
+const CLIENT_PATH = path.join(PLUGIN_DIR, "client.js");
+const STYLES_PATH = path.join(PACKAGE_ROOT, "src", "styles.css");
+export default function ask(input) {
+    const opts = parseOptions(input);
+    return {
+        name: "@dogsbay/plugin-ask",
+        clientModules() {
+            return [CLIENT_PATH];
+        },
+        styles() {
+            return [STYLES_PATH];
+        },
+        defineClientConfig() {
+            // JSON-safe runtime config exposed at
+            // virtual:dogsbay-plugin-config/@dogsbay/plugin-ask
+            return {
+                endpoint: opts.endpoint,
+                site: opts.site,
+                mode: opts.mode,
+                buttonLabel: opts.buttonLabel,
+                title: opts.title,
+                placeholder: opts.placeholder,
+                position: opts.position,
+            };
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,YAAY,EAAmB,MAAM,aAAa,CAAC;AAE5D,6EAA6E;AAC7E,oEAAoE;AACpE,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAChE,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;AACpD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;AACvD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;AAIjE,MAAM,CAAC,OAAO,UAAU,GAAG,CAAC,KAAkB;IAC5C,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IAEjC,OAAO;QACL,IAAI,EAAE,qBAAqB;QAE3B,aAAa;YACX,OAAO,CAAC,WAAW,CAAC,CAAC;QACvB,CAAC;QAED,MAAM;YACJ,OAAO,CAAC,WAAW,CAAC,CAAC;QACvB,CAAC;QAED,kBAAkB;YAChB,sCAAsC;YACtC,oDAAoD;YACpD,OAAO;gBACL,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,QAAQ,EAAE,IAAI,CAAC,QAAQ;aACxB,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/protocol.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Wire protocol shared between the client widget and the dogsbay-ask proxy.
+ * Kept dependency-free and DOM-free so it is unit-testable in Node.
+ */
+import type { AskMode } from "./schema.js";
+export interface AskRequest {
+    site: string;
+    query: string;
+    mode: AskMode;
+}
+/** Build the JSON body the proxy expects. Trims the query. */
+export declare function buildAskRequest(site: string, query: string, mode: AskMode): AskRequest;
+/**
+ * Tolerant extraction of human-readable text from a streamed proxy chunk.
+ *
+ * The proxy passes AI Search's streamed answer straight through. Depending on
+ * the instance/model that arrives either as raw text or as SSE `data:` frames.
+ * This strips common SSE framing and ignores the `[DONE]` sentinel so the
+ * widget can append whatever is left. Returns "" for control-only lines.
+ *
+ * NOTE: citation/structured-answer rendering is finalized against a live
+ * instance — see README "Streaming format".
+ */
+export declare function extractText(chunk: string): string;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AAED,8DAA8D;AAC9D,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,UAAU,CAEtF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CA8BjD"}

package/dist/protocol.js

@@ -0,0 +1,51 @@
+/** Build the JSON body the proxy expects. Trims the query. */
+export function buildAskRequest(site, query, mode) {
+    return { site, query: query.trim(), mode };
+}
+/**
+ * Tolerant extraction of human-readable text from a streamed proxy chunk.
+ *
+ * The proxy passes AI Search's streamed answer straight through. Depending on
+ * the instance/model that arrives either as raw text or as SSE `data:` frames.
+ * This strips common SSE framing and ignores the `[DONE]` sentinel so the
+ * widget can append whatever is left. Returns "" for control-only lines.
+ *
+ * NOTE: citation/structured-answer rendering is finalized against a live
+ * instance — see README "Streaming format".
+ */
+export function extractText(chunk) {
+    return chunk
+        .split(/\r?\n/)
+        .map((line) => {
+        const trimmed = line.trimStart();
+        if (trimmed === "")
+            return "";
+        // Drop SSE control framing (event:/id:/retry:/comment) — only `data:`
+        // lines carry content. A `data: [...]` chunks array parses to an array
+        // with no token field and is harmlessly skipped below.
+        if (/^(event|id|retry):/.test(trimmed) || trimmed.startsWith(":"))
+            return "";
+        if (!trimmed.startsWith("data:"))
+            return line;
+        const payload = trimmed.slice("data:".length).trim();
+        if (payload === "" || payload === "[DONE]")
+            return "";
+        // Try to pull a token out of a JSON event; else emit raw payload.
+        // Handles OpenAI-compatible chat-completions chunks
+        // ({choices:[{delta:{content}}]}) plus a few simpler shapes.
+        try {
+            const obj = JSON.parse(payload);
+            const token = obj.choices?.[0]?.delta?.content ??
+                obj.choices?.[0]?.message?.content ??
+                obj.response ??
+                obj.text ??
+                obj.delta;
+            return typeof token === "string" ? token : "";
+        }
+        catch {
+            return payload;
+        }
+    })
+        .join("");
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAYA,8DAA8D;AAC9D,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,KAAa,EAAE,IAAa;IACxE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,KAAK;SACT,KAAK,CAAC,OAAO,CAAC;SACd,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACZ,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QACjC,IAAI,OAAO,KAAK,EAAE;YAAE,OAAO,EAAE,CAAC;QAC9B,sEAAsE;QACtE,uEAAuE;QACvE,uDAAuD;QACvD,IAAI,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,CAAC;QAC7E,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC;QAC9C,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QACrD,IAAI,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QACtD,kEAAkE;QAClE,oDAAoD;QACpD,6DAA6D;QAC7D,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAwB,CAAC;YACvD,MAAM,KAAK,GACT,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO;gBAChC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO;gBAClC,GAAG,CAAC,QAAQ;gBACZ,GAAG,CAAC,IAAI;gBACR,GAAG,CAAC,KAAK,CAAC;YACZ,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAChD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC,CAAC;SACD,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC"}

package/dist/schema.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Options schema for `@dogsbay/plugin-ask`.
+ *
+ * Hand-rolled validation (no Zod dep), matching the convention in
+ * `@dogsbay/plugin-image-zoom`. `parseOptions` returns a fully-resolved
+ * options object with every field set to either the user value or the
+ * documented default. `endpoint` and `site` are REQUIRED — the widget is
+ * useless without a backend to call and a site id to route by.
+ */
+export type AskMode = "answer" | "search";
+export type AskPosition = "bottom-right" | "bottom-left";
+export interface AskOptions {
+    /**
+     * URL of the dogsbay-ask proxy (the shared Worker). Required.
+     * Example: "https://dogsbay-ask.<subdomain>.workers.dev".
+     */
+    endpoint?: string;
+    /**
+     * Site id sent to the proxy to select the AI Search instance. Required.
+     * This is the site's GitHub Pages subfolder / Dogsbay base path, e.g.
+     * "openshift-docs-dogsbay". Must match a key in the proxy's SITES map.
+     */
+    site?: string;
+    /** Retrieval mode: "answer" (RAG answer, default) or "search" (chunks). */
+    mode?: AskMode;
+    /** Floating button label. Default "Ask AI". */
+    buttonLabel?: string;
+    /** Modal heading. Default "Ask the docs". */
+    title?: string;
+    /** Input placeholder. Default "Ask a question…". */
+    placeholder?: string;
+    /** Corner the floating button sits in. Default "bottom-right". */
+    position?: AskPosition;
+}
+export interface ResolvedAskOptions {
+    endpoint: string;
+    site: string;
+    mode: AskMode;
+    buttonLabel: string;
+    title: string;
+    placeholder: string;
+    position: AskPosition;
+}
+/**
+ * Validate + resolve user options. Throws structured errors naming the
+ * offending field so users see a clear message rather than a stack trace.
+ */
+export declare function parseOptions(input: unknown): ResolvedAskOptions;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAC1C,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,aAAa,CAAC;AAEzD,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,WAAW,CAAC;CACvB;AAYD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CA8B/D"}

package/dist/schema.js

@@ -0,0 +1,74 @@
+/**
+ * Options schema for `@dogsbay/plugin-ask`.
+ *
+ * Hand-rolled validation (no Zod dep), matching the convention in
+ * `@dogsbay/plugin-image-zoom`. `parseOptions` returns a fully-resolved
+ * options object with every field set to either the user value or the
+ * documented default. `endpoint` and `site` are REQUIRED — the widget is
+ * useless without a backend to call and a site id to route by.
+ */
+const DEFAULTS = {
+    mode: "answer",
+    buttonLabel: "Ask AI",
+    title: "Ask the docs",
+    placeholder: "Ask a question…",
+    position: "bottom-right",
+};
+const PKG = "@dogsbay/plugin-ask";
+/**
+ * Validate + resolve user options. Throws structured errors naming the
+ * offending field so users see a clear message rather than a stack trace.
+ */
+export function parseOptions(input) {
+    if (input === undefined || input === null || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error(`${PKG}: options are required and must be an object with at least { endpoint, site }, got ${describe(input)}.`);
+    }
+    const opts = input;
+    const endpoint = requireUrl(opts.endpoint, "endpoint");
+    const site = requireNonEmptyString(opts.site, "site");
+    const out = { ...DEFAULTS, endpoint, site };
+    if (opts.mode !== undefined) {
+        if (opts.mode !== "answer" && opts.mode !== "search") {
+            throw new Error(`${PKG}: options.mode must be "answer" or "search".`);
+        }
+        out.mode = opts.mode;
+    }
+    if (opts.buttonLabel !== undefined)
+        out.buttonLabel = requireNonEmptyString(opts.buttonLabel, "buttonLabel");
+    if (opts.title !== undefined)
+        out.title = requireNonEmptyString(opts.title, "title");
+    if (opts.placeholder !== undefined)
+        out.placeholder = requireNonEmptyString(opts.placeholder, "placeholder");
+    if (opts.position !== undefined) {
+        if (opts.position !== "bottom-right" && opts.position !== "bottom-left") {
+            throw new Error(`${PKG}: options.position must be "bottom-right" or "bottom-left".`);
+        }
+        out.position = opts.position;
+    }
+    return out;
+}
+function requireNonEmptyString(value, field) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`${PKG}: options.${field} must be a non-empty string.`);
+    }
+    return value;
+}
+function requireUrl(value, field) {
+    const s = requireNonEmptyString(value, field);
+    try {
+        // eslint-disable-next-line no-new
+        new URL(s);
+    }
+    catch {
+        throw new Error(`${PKG}: options.${field} must be a valid absolute URL, got "${s}".`);
+    }
+    return s;
+}
+function describe(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@dogsbay/plugin-ask",
+  "version": "0.2.0-beta.81",
+  "description": "Floating \"Ask AI\" widget for Dogsbay docs sites — calls a shared AI Search proxy (dogsbay-ask).",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": "./dist/client.js",
+    "./styles.css": "./src/styles.css"
+  },
+  "files": [
+    "dist",
+    "src/styles.css",
+    "src/client.ts",
+    "skills",
+    "README.md"
+  ],
+  "dependencies": {
+    "@dogsbay/types": "0.2.0-beta.81"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "@types/node": "^22.0.0"
+  },
+  "license": "MIT",
+  "keywords": [
+    "dogsbay",
+    "dogsbay-plugin",
+    "documentation",
+    "ai-search",
+    "rag",
+    "ask-ai"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dogsbay/dogsbay.git",
+    "directory": "packages/plugin-ask"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/skills/ask-config.md

@@ -0,0 +1,46 @@
+---
+name: plugin-ask-config
+description: Configure the @dogsbay/plugin-ask "Ask AI" widget — endpoint, site id, and presentation options — in dogsbay.config.yml. Use when adding or debugging the Ask AI button on a Dogsbay docs site.
+---
+
+# Configuring @dogsbay/plugin-ask
+
+`@dogsbay/plugin-ask` adds a floating "Ask AI" button to every page. It sends
+the question to a configured backend and shows the answer, so the docs site
+stays static and holds no secrets.
+
+## Enable it
+
+```yaml
+# dogsbay.config.yml
+plugins:
+  - name: "@dogsbay/plugin-ask"
+    options:
+      endpoint: "https://<your-ask-endpoint>"
+      site: "openshift-docs-dogsbay"
+```
+
+- **`endpoint`** (required) — URL of the backend the widget calls.
+- **`site`** (required) — the site id sent with each request so the backend
+  knows which corpus to answer from. Conventionally the site's base path /
+  GitHub Pages subfolder, e.g. `tigera-dogsbay`. The team operating the backend
+  owns the `site` → corpus mapping; use the value they give you.
+
+Optional presentation: `mode` (`answer` | `search`), `buttonLabel`, `title`,
+`placeholder`, `position` (`bottom-right` | `bottom-left`).
+
+## When it isn't working
+
+1. **Button not appearing** — confirm the plugin is listed under `plugins:` and
+   that `dogsbay site build` ran; the widget mounts via a client module on every
+   page.
+2. **Errors when asking** — confirm `endpoint` is reachable from the browser and
+   that `site` matches the value the backend expects.
+3. **Empty or "I don't know" answers** — the backend's corpus may not be ready;
+   check with whoever operates the endpoint.
+
+## Styling
+
+Styles use Dogsbay theme tokens (`--color-accent`, `--color-surface`,
+`--radius`, …) with fallbacks, so the widget picks up the site theme. Override
+the `.dba-*` classes in your own CSS to customize further.

package/src/client.ts

@@ -0,0 +1,139 @@
+/**
+ * Client runtime for `@dogsbay/plugin-ask`.
+ *
+ * Imported via the auto-generated `src/lib/plugin-runtime.ts` in the user's
+ * Astro project, so it runs for side effects on every page. It injects a
+ * floating button + <dialog> at <body> level (outside the article), and on
+ * submit streams an answer from the dogsbay-ask proxy.
+ *
+ * Astro view transitions: the document is swapped on navigation, so we mount
+ * on `astro:page-load` and tear down on `astro:before-swap` to avoid stale
+ * nodes / duplicate buttons.
+ */
+// @ts-expect-error: virtual module resolved by the Dogsbay Vite alias at build.
+import config from "virtual:dogsbay-plugin-config/@dogsbay/plugin-ask";
+import { buildAskRequest, extractText } from "./protocol.js";
+import type { AskMode, AskPosition } from "./schema.js";
+
+interface RuntimeConfig {
+  endpoint: string;
+  site: string;
+  mode: AskMode;
+  buttonLabel: string;
+  title: string;
+  placeholder: string;
+  position: AskPosition;
+}
+
+const cfg = config as RuntimeConfig;
+
+const ROOT_ID = "dba-root";
+
+function mount(): void {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(ROOT_ID)) return; // already mounted
+
+  const root = document.createElement("div");
+  root.id = ROOT_ID;
+  root.dataset.position = cfg.position;
+
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = "dba-trigger";
+  button.textContent = cfg.buttonLabel;
+  button.setAttribute("aria-haspopup", "dialog");
+
+  const dialog = document.createElement("dialog");
+  dialog.className = "dba-dialog";
+  dialog.setAttribute("aria-label", cfg.title);
+  dialog.innerHTML = `
+    <form class="dba-form" method="dialog">
+      <header class="dba-header">
+        <h2 class="dba-title"></h2>
+        <button type="button" class="dba-close" aria-label="Close">×</button>
+      </header>
+      <div class="dba-inputrow">
+        <input class="dba-input" type="text" autocomplete="off" enterkeyhint="search" />
+        <button type="submit" class="dba-submit">Ask</button>
+      </div>
+      <div class="dba-answer" aria-live="polite" tabindex="-1"></div>
+    </form>
+  `;
+
+  // textContent (not innerHTML) for user-configurable strings — no injection.
+  dialog.querySelector<HTMLHeadingElement>(".dba-title")!.textContent = cfg.title;
+  const input = dialog.querySelector<HTMLInputElement>(".dba-input")!;
+  input.placeholder = cfg.placeholder;
+  const answer = dialog.querySelector<HTMLDivElement>(".dba-answer")!;
+  const form = dialog.querySelector<HTMLFormElement>(".dba-form")!;
+  const submit = dialog.querySelector<HTMLButtonElement>(".dba-submit")!;
+
+  button.addEventListener("click", () => {
+    dialog.showModal();
+    input.focus();
+  });
+  dialog.querySelector<HTMLButtonElement>(".dba-close")!.addEventListener("click", () => dialog.close());
+
+  form.addEventListener("submit", async (e) => {
+    e.preventDefault();
+    const query = input.value.trim();
+    if (!query) return;
+
+    submit.disabled = true;
+    answer.dataset.state = "loading";
+    answer.textContent = "…";
+
+    try {
+      const res = await fetch(cfg.endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(buildAskRequest(cfg.site, query, cfg.mode)),
+      });
+      if (!res.ok || !res.body) {
+        throw new Error(`Request failed (${res.status})`);
+      }
+      answer.textContent = "";
+      answer.dataset.state = "streaming";
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let buf = "";
+      for (;;) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buf += decoder.decode(value, { stream: true });
+        // Only process complete lines; keep any partial line buffered so a
+        // `data:` frame split across reads isn't parsed half-formed.
+        const nl = buf.lastIndexOf("\n");
+        if (nl >= 0) {
+          answer.textContent += extractText(buf.slice(0, nl + 1));
+          buf = buf.slice(nl + 1);
+        }
+      }
+      if (buf) answer.textContent += extractText(buf);
+      answer.dataset.state = "done";
+    } catch (err) {
+      answer.dataset.state = "error";
+      answer.textContent = `Sorry — something went wrong. ${(err as Error).message}`;
+    } finally {
+      submit.disabled = false;
+    }
+  });
+
+  root.append(button, dialog);
+  document.body.appendChild(root);
+}
+
+function unmount(): void {
+  if (typeof document === "undefined") return;
+  document.getElementById(ROOT_ID)?.remove();
+}
+
+if (typeof document !== "undefined") {
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", mount);
+  } else {
+    mount();
+  }
+  document.addEventListener("astro:page-load", mount);
+  document.addEventListener("astro:before-swap", unmount);
+}

package/src/styles.css

@@ -0,0 +1,82 @@
+/**
+ * Styles for @dogsbay/plugin-ask. Uses Dogsbay theme tokens where available
+ * with safe fallbacks, so it themes automatically but never breaks if a token
+ * is missing. All selectors are namespaced under .dba- to avoid collisions.
+ */
+
+#dba-root {
+  --dba-accent: var(--color-accent, #2563eb);
+  --dba-accent-contrast: var(--color-accent-contrast, #ffffff);
+  --dba-surface: var(--color-surface, #ffffff);
+  --dba-text: var(--color-text, #1f2937);
+  --dba-border: var(--color-border, #e5e7eb);
+  --dba-radius: var(--radius, 0.5rem);
+}
+
+.dba-trigger {
+  position: fixed;
+  bottom: 1.25rem;
+  z-index: 60;
+  padding: 0.625rem 1rem;
+  font: inherit;
+  font-weight: 600;
+  color: var(--dba-accent-contrast);
+  background: var(--dba-accent);
+  border: none;
+  border-radius: 999px;
+  box-shadow: 0 2px 10px rgb(0 0 0 / 0.18);
+  cursor: pointer;
+}
+#dba-root[data-position="bottom-right"] .dba-trigger { right: 1.25rem; }
+#dba-root[data-position="bottom-left"] .dba-trigger { left: 1.25rem; }
+.dba-trigger:hover { filter: brightness(1.05); }
+.dba-trigger:focus-visible { outline: 2px solid var(--dba-accent); outline-offset: 2px; }
+
+.dba-dialog {
+  width: min(40rem, 92vw);
+  max-height: 80vh;
+  padding: 0;
+  color: var(--dba-text);
+  background: var(--dba-surface);
+  border: 1px solid var(--dba-border);
+  border-radius: var(--dba-radius);
+  box-shadow: 0 10px 40px rgb(0 0 0 / 0.25);
+}
+.dba-dialog::backdrop { background: rgb(0 0 0 / 0.4); }
+
+.dba-form { display: flex; flex-direction: column; gap: 0.75rem; padding: 1rem 1.25rem 1.25rem; }
+.dba-header { display: flex; align-items: center; justify-content: space-between; }
+.dba-title { margin: 0; font-size: 1.05rem; }
+.dba-close {
+  font-size: 1.5rem; line-height: 1; padding: 0 0.25rem;
+  color: inherit; background: none; border: none; cursor: pointer; opacity: 0.6;
+}
+.dba-close:hover { opacity: 1; }
+
+.dba-inputrow { display: flex; gap: 0.5rem; }
+.dba-input {
+  flex: 1; padding: 0.55rem 0.75rem; font: inherit;
+  color: var(--dba-text); background: var(--dba-surface);
+  border: 1px solid var(--dba-border); border-radius: var(--dba-radius);
+}
+.dba-input:focus-visible { outline: 2px solid var(--dba-accent); outline-offset: 1px; }
+.dba-submit {
+  padding: 0.55rem 1rem; font: inherit; font-weight: 600;
+  color: var(--dba-accent-contrast); background: var(--dba-accent);
+  border: none; border-radius: var(--dba-radius); cursor: pointer;
+}
+.dba-submit:disabled { opacity: 0.6; cursor: progress; }
+
+.dba-answer {
+  min-height: 2rem; max-height: 50vh; overflow-y: auto;
+  padding: 0.75rem; white-space: pre-wrap; line-height: 1.55;
+  background: color-mix(in srgb, var(--dba-text) 4%, transparent);
+  border-radius: var(--dba-radius);
+}
+.dba-answer[data-state="loading"] { opacity: 0.6; }
+.dba-answer[data-state="error"] { color: #b91c1c; }
+
+@media (prefers-reduced-motion: no-preference) {
+  .dba-dialog[open] { animation: dba-in 0.12s ease-out; }
+}
+@keyframes dba-in { from { transform: translateY(6px); opacity: 0; } to { transform: none; opacity: 1; } }