sgiant-ai-widget 1.0.0 → 1.1.0

package/README.md

@@ -10,8 +10,17 @@ and one runtime dependency.
 npm install sgiant-ai-widget
 ```
 
-**[Live example →](https://vedatugur.github.io/sgiant-ai-widget/)** — a plain
-HTML page with no bundler and no build step.
+**Live examples**, all plain HTML with no bundler and no build step:
+
+- **[Quick start →](https://vedatugur.github.io/sgiant-ai-widget/)** — a
+  `<script src>` tag and one call.
+- **[Beyond streaming text →](https://vedatugur.github.io/sgiant-ai-widget/capabilities.html)**
+  — live activity steps, the assistant asking the human to decide, a
+  confirm-gated write, suggestion chips, a form the model designed, a card with
+  its own actions, and a renderer you register yourself. Every demo runs a real
+  turn and shows the JSON that produced it.
+- **[Theming →](https://vedatugur.github.io/sgiant-ai-widget/theming.html)** —
+  launcher geometry as custom properties, and an inline SVG brand mark.
 
 ## Two ways in
 
@@ -60,7 +69,15 @@ read in one go, is in **[BACKEND.md](./BACKEND.md)**.
 
 The entire stylesheet reads from `--aiw-*` CSS custom properties set on the
 widget's roots. `accent` / `gradient` are the shorthand; the `theme` option
-overrides any token — or theme from plain CSS by targeting the roots.
+overrides any token — or theme from plain CSS by targeting the roots, which
+works because the defaults are declared inside `:where()` and therefore carry
+zero specificity. Any rule you write beats them, with no `!important` needed.
+
+**Launcher geometry is tokenised too**: `--aiw-launcher-size`, `-offset`,
+`-offset-sm` (below 480px), `-icon`, `-pill-height`, `-pill-icon`,
+`-parked-size`, `-parked-icon`, `-dot`, `-dot-sm`. The `-sm` pair is
+deliberately independent, so a larger desktop launcher does not force a larger
+one on a phone. See [examples/theming.html](./examples/theming.html).
 
 ```ts
 createAiChatWidget({

package/dist/index.d.ts

@@ -216,6 +216,22 @@ export interface AiChatWidgetOptions {
     subtitle?: string;
     /** Avatar image URL (the brand logo mark). Falls back to a crescent glyph. */
     avatarUrl?: string;
+    /**
+     * The brand mark as an INLINE SVG string, e.g. `"<svg viewBox=…>…</svg>"`.
+     *
+     * Wins over `avatarUrl`. An `<img>` cannot inherit the widget's colours or
+     * stay crisp at every launcher size, and it costs a network round trip before
+     * the bubble looks like itself — which is why a bitmap was never enough for a
+     * package other companies brand.
+     *
+     * THIS IS MARKUP AND IT IS INSERTED AS MARKUP. Pass a mark YOU authored, the
+     * same way you would write it into your own page. Never build this string
+     * from user input, a URL parameter, or anything a model produced. The only
+     * check made here is that it looks like an `<svg>` root and carries no
+     * `<script>` — that is a guard against an obvious mistake, NOT sanitisation,
+     * and it will not save you from hostile input.
+     */
+    avatarSvg?: string;
     /** CSS gradient for the chrome (header/bubble) for a premium look. */
     gradient?: string;
     greeting?: string;

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -83,6 +83,51 @@ export { gateNavigationTarget } from "./safe-url.js";
 // and the file an embedder must point at to replace the mark (#306:
 // `avatarUrl` only accepts a bitmap today).
 import { AVATAR_DEFS, AVATAR_SVG, ICON_HISTORY, ICON_EXPAND, ICON_COLLAPSE, ICON_COMPASS, ICON_ADVANCED, ICON_CHEVRON_R, ICON_DOWNLOAD, ICON_FLAG, ICON_BELL, ICON_BELL_OFF, ICON_MORE, ICON_ATTACH, ICON_EDIT, ICON_REGEN, ICON_THUMB_UP, ICON_THUMB_DOWN, } from "./icons.js";
+/**
+ * Warn a host about a malformed frame — once per reason, per page.
+ *
+ * Once, because a stream can carry the same bad frame on every turn and a
+ * console flooded with one message is a console nobody reads. Per reason, so a
+ * second, different mistake is still surfaced.
+ */
+const warned = new Set();
+function warnOnce(reason, message) {
+    if (warned.has(reason))
+        return;
+    warned.add(reason);
+    try {
+        console.warn(message);
+    }
+    catch {
+        /* a host that has replaced console is not a reason to break the turn */
+    }
+}
+/**
+ * Choose the brand mark: an inline SVG the host authored, a bitmap URL, or the
+ * built-in crescent.
+ *
+ * The SVG check is deliberately narrow. It refuses anything that is not an
+ * `<svg>` root, and anything containing a `<script>` — enough to turn "I passed
+ * the wrong thing" into a clear error instead of broken markup, and honest
+ * about being nothing more than that. Real sanitisation of arbitrary SVG is a
+ * library's job, and a host that needs one should run it before calling here.
+ */
+function pickAvatar(opts, name) {
+    const svg = opts.avatarSvg?.trim();
+    if (svg) {
+        if (!/^<svg[\s>]/i.test(svg))
+            throw new Error("createAiChatWidget: `avatarSvg` must be an inline <svg> string. " +
+                "For an image URL use `avatarUrl` instead.");
+        if (/<script/i.test(svg))
+            throw new Error("createAiChatWidget: `avatarSvg` contains a <script> tag. This option " +
+                "inserts markup — pass a mark you authored, never anything built " +
+                "from user input.");
+        return svg;
+    }
+    if (opts.avatarUrl)
+        return `<img src="${escapeHtml(opts.avatarUrl)}" alt="${escapeHtml(name)}" class="${PREFIX}-av-img"/>`;
+    return AVATAR_SVG;
+}
 export function createAiChatWidget(opts) {
     const accent = opts.accent ?? "#6d28d9";
     const gradient = opts.gradient ?? `linear-gradient(135deg,${accent},${accent})`;
@@ -99,10 +144,13 @@ export function createAiChatWidget(opts) {
                 s = s.split(`{${p}}`).join(String(params[p]));
         return s;
     };
-    // Avatar markup: the brand logo mark (img) when given, else a crescent glyph.
-    const avatarInner = opts.avatarUrl
-        ? `<img src="${opts.avatarUrl}" alt="${name}" class="${PREFIX}-av-img"/>`
-        : AVATAR_SVG;
+    // Avatar markup: an inline SVG mark, else a bitmap, else the crescent glyph.
+    //
+    // `avatarUrl` was interpolated into the src attribute unescaped until
+    // 2026-09-03. A host passing a URL containing a double quote broke out of the
+    // attribute — the kind of thing that stays harmless right up until someone
+    // builds that URL from a tenant record.
+    const avatarInner = pickAvatar(opts, name);
     /** Aborted by `destroy()`. Every in-flight turn is tied to it, so a widget
      *  that has been torn down stops writing to its own dead DOM and storage. */
     const alive = new AbortController();
@@ -4169,6 +4217,22 @@ export function createAiChatWidget(opts) {
                             producedAny = true;
                         }
                         // The assistant is ASKING the human to decide something.
+                        //
+                        // A question frame missing `questionId` or `prompt` used to be
+                        // dropped in SILENCE — no render, no error, nothing in the console.
+                        // A backend author following BACKEND.md wrote a question, watched
+                        // the reply arrive without it, and had no way to tell whether the
+                        // widget did not support questions or their frame was wrong.
+                        // `questionId` is optional on StreamFrame and mandatory here, and
+                        // BACKEND.md did not mention it at all until 2026-09-03.
+                        //
+                        // Silence is the worst failure a protocol can have. Say what is
+                        // missing, once, and carry on with the rest of the turn.
+                        if (frame.type === "question" && !(frame.questionId && frame.prompt))
+                            warnOnce("question-frame-incomplete", "sgiant-ai-widget: ignoring a `question` frame without " +
+                                `${!frame.questionId ? "`questionId`" : "`prompt`"}. Both are ` +
+                                "required — the id is echoed back with the user's answer so " +
+                                "your backend knows which question was answered. See BACKEND.md.");
                         if (frame.type === "question" &&
                             frame.questionId &&
                             frame.prompt &&