sgiant-ai-widget 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vedat Aydın Uğur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# sgiant-ai-widget
+
+A framework-agnostic, embeddable **AI chat widget**. One call mounts a floating
+bubble and a streaming chat panel into any page.
+
+No React. No framework. Vanilla DOM, themeable through CSS custom properties,
+and one runtime dependency.
+
+```bash
+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.
+
+## Two ways in
+
+### As a module (React, Next, Vue, Svelte, plain ESM)
+
+```ts
+import { createAiChatWidget } from "sgiant-ai-widget";
+
+const chat = createAiChatWidget({
+  endpoint: "https://api.example.com/chat",
+  title: "Aria",
+  greeting: "Hi! Ask me anything.",
+  accent: "#6d28d9",
+});
+chat.open();
+```
+
+### As a `<script>` tag, no build step
+
+```html
+<script src="https://unpkg.com/sgiant-ai-widget/dist/sgiant-ai-widget.global.js"></script>
+<script>
+  SgiantAiWidget.createAiChatWidget({ endpoint: "/chat" });
+</script>
+```
+
+The global build bundles its one dependency, so it is a single file. If your
+page already uses a bundler, prefer the module build — it shares that dependency
+instead of carrying a second copy.
+
+## The backend
+
+One POST endpoint that streams newline-delimited JSON. Four frame types matter:
+
+| frame | meaning |
+| --- | --- |
+| `{"type":"text","d":"…"}` | append this text |
+| `{"threadId":"…"}` | name the conversation |
+| `{"type":"done"}` | the turn is over |
+| `{"type":"error","message":"…"}` | the turn failed |
+
+The full contract, including a dependency-free reference server short enough to
+read in one go, is in **[BACKEND.md](./BACKEND.md)**.
+
+## Theming
+
+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.
+
+```ts
+createAiChatWidget({
+  // …
+  accent: "#6d28d9",
+  theme: {
+    // dark mode
+    surface: "#16161e",
+    "surface-2": "#22222c",
+    bg: "#101016",
+    text: "#e7e7ec",
+    "text-2": "#b6b6c2",
+    muted: "#8a8a96",
+    border: "#2b2b36",
+    "border-strong": "#3a3a48",
+    "border-soft": "#22222c",
+  },
+});
+```
+
+Tokens: `accent`, `accent-contrast`, `gradient`, `surface`, `surface-2`, `bg`,
+`text`, `text-2`, `muted`, `border`, `border-strong`, `border-soft`.
+
+## Custom renderers (extension point)
+
+The assistant can emit `[[<tag>:{json}]]` directives; built-ins cover
+`widget` (stat/kpis/list/table), `preview` (sandboxed HTML), `navigate`,
+`action`, `chips`, and `form`. Register your own tags to render anything else —
+the widget strips the directive, mounts a host element in the log, and hands
+you the parsed JSON:
+
+```ts
+const chat = createAiChatWidget({
+  // …
+  renderers: {
+    calendar: (host, spec) => {
+      host.textContent = renderMyCalendar(spec); // validate spec yourself
+      return () => cleanup(); // optional disposer (message cleared)
+    },
+  },
+});
+// or later:
+chat.registerRenderer("map", (host, spec) => drawMap(host, spec));
+```
+
+Built-in tags are reserved (a plugin can't hijack the confirm-gated
+`action`/`form` security model). A throwing renderer removes its host card
+instead of breaking the message.
+
+## Charts without React
+
+In-app hosts wire `renderDataWidget` (real `@sgiant/ui` charts). A standalone
+embed has no React, so `render_chart` frames degrade to a stat/table — unless
+you plug `renderChartFallback(host, spec, rows, comparisonRows)` with any
+lightweight chart lib.
+
+## Transport
+
+POSTs `{ accountId, threadId, content }` and reads a streamed body, tolerating
+both shapes the platform emits:
+
+- SSE — `data: {"type":"assistant_delta","text":"…"}`
+- NDJSON — `{"d":"…"}`
+
+plus `{type:"thread",threadId}`, `{type:"error",message}`, `{type:"done"}`.
+
+## Security
+
+The widget holds no long-lived secret — the host supplies a token (Clerk session
+in-app, or a short-lived **embed token** for external sites). The backend's OBO
+scoping is the real ceiling; this is presentation only. The public embed-token
+endpoint is the next backend step (tracked with the managed-AI build).
+
+## External embedding
+
+For drop-in `<script>` use on third-party sites, bundle this module to a single
+IIFE/UMD file that exposes `window.SgiantChat.init(opts)` — not yet wired (needs
+the embed-token endpoint first).
+
+## About the `#123` references in the source
+
+The comments cite issue numbers from the private tracker this widget was built
+in, where it lived inside a monorepo until 2026-09-02. They are kept because the
+reasoning around them is worth more than the tidiness of removing it — a comment
+explaining *why* a wire value must not change is useful even when you cannot
+open the ticket it cites.
+
+Nothing behind those numbers is needed to use, read, or modify this package.
+
+## Licence
+
+MIT © Vedat Aydın Uğur

package/dist/ai-invalidation.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A cross-tab "the assistant changed something" bus.
+ *
+ * Deliberately knows NOTHING about what changed: it carries an account id and a
+ * list of opaque domain strings, and the host decides what they mean. sgiant's
+ * mapping from those strings to query keys lives in `@sgiant/ai-apply`, because
+ * it is a description of sgiant's product rather than of this widget.
+ */
+export interface AiChangeEvent {
+    accountId: string;
+    domains?: string[];
+}
+/** Tell other tabs an AI change landed so they invalidate too. No-op where
+ *  BroadcastChannel is unavailable (old browsers / SSR). */
+export declare function broadcastAiChange(accountId: string, domains?: string[]): void;
+/** Subscribe to cross-tab AI change events; returns an unsubscribe fn. */
+export declare function subscribeAiChange(cb: (e: AiChangeEvent) => void): () => void;
+export interface LiveSyncOptions {
+    /** The SSE endpoint, e.g. `${API_BASE}/accounts/:id/live`. */
+    url: string;
+    /** Fresh auth token per (re)connect. */
+    getToken: () => Promise<string | null>;
+    /** Called for each change event the server pushes. */
+    onChange: (accountId: string, domains?: string[]) => void;
+}
+/** Subscribe to the server's live-sync stream. Returns an unsubscribe fn. No-op
+ *  where fetch/streams are unavailable (SSR). */
+export declare function subscribeLiveSync(opts: LiveSyncOptions): () => void;
+//# sourceMappingURL=ai-invalidation.d.ts.map

package/dist/ai-invalidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-invalidation.d.ts","sourceRoot":"","sources":["../src/ai-invalidation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;4DAC4D;AAC5D,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAsB7E;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,aAAa,KAAK,IAAI,GAAG,MAAM,IAAI,CAgB5E;AAQD,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,wCAAwC;IACxC,QAAQ,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACvC,sDAAsD;IACtD,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CAC3D;AAED;iDACiD;AACjD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,IAAI,CA0DnE"}

package/dist/ai-invalidation.js

@@ -0,0 +1,121 @@
+/**
+ * A cross-tab "the assistant changed something" bus.
+ *
+ * Deliberately knows NOTHING about what changed: it carries an account id and a
+ * list of opaque domain strings, and the host decides what they mean. sgiant's
+ * mapping from those strings to query keys lives in `@sgiant/ai-apply`, because
+ * it is a description of sgiant's product rather than of this widget.
+ */
+// Neutral, like the bridge's channel: this ships to people whose product is
+// not sgiant. It is a WIRE value between tabs of one deployment, so a change
+// only costs an old tab and a new tab not seeing each other until reload.
+const AI_LIVE_CHANNEL = "ai-widget-live";
+/** Tell other tabs an AI change landed so they invalidate too. No-op where
+ *  BroadcastChannel is unavailable (old browsers / SSR). */
+export function broadcastAiChange(accountId, domains) {
+    // SAME-TAB listeners (e.g. the brand info bar's live "updated by AI" status)
+    // get a synchronous window event — BroadcastChannel is meant for OTHER tabs and
+    // is the less reliable path within one document, so this is the primary signal
+    // for anything on the current page; BroadcastChannel below still covers tabs.
+    if (typeof window !== "undefined") {
+        try {
+            window.dispatchEvent(new CustomEvent(AI_LIVE_CHANNEL, { detail: { accountId, domains } }));
+        }
+        catch {
+            /* CustomEvent unavailable */
+        }
+    }
+    if (typeof BroadcastChannel === "undefined")
+        return;
+    try {
+        const ch = new BroadcastChannel(AI_LIVE_CHANNEL);
+        ch.postMessage({ accountId, domains });
+        ch.close();
+    }
+    catch {
+        /* channel unavailable */
+    }
+}
+/** Subscribe to cross-tab AI change events; returns an unsubscribe fn. */
+export function subscribeAiChange(cb) {
+    if (typeof BroadcastChannel === "undefined")
+        return () => { };
+    const ch = new BroadcastChannel(AI_LIVE_CHANNEL);
+    const handler = (ev) => {
+        const d = ev.data;
+        if (d && typeof d.accountId === "string")
+            cb({
+                accountId: d.accountId,
+                domains: Array.isArray(d.domains) ? d.domains : undefined,
+            });
+    };
+    ch.addEventListener("message", handler);
+    return () => {
+        ch.removeEventListener("message", handler);
+        ch.close();
+    };
+}
+/** Subscribe to the server's live-sync stream. Returns an unsubscribe fn. No-op
+ *  where fetch/streams are unavailable (SSR). */
+export function subscribeLiveSync(opts) {
+    if (typeof fetch === "undefined")
+        return () => { };
+    let closed = false;
+    let ctrl = null;
+    let backoff = 1000;
+    const connect = async () => {
+        if (closed)
+            return;
+        ctrl = new AbortController();
+        try {
+            const token = await opts.getToken();
+            const res = await fetch(opts.url, {
+                headers: token ? { authorization: `Bearer ${token}` } : {},
+                credentials: "include",
+                signal: ctrl.signal,
+            });
+            if (!res.ok || !res.body)
+                throw new Error(`live ${res.status}`);
+            backoff = 1000; // connected — reset backoff
+            const reader = res.body.getReader();
+            const dec = new TextDecoder();
+            let buf = "";
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done || closed)
+                    break;
+                buf += dec.decode(value, { stream: true });
+                let nl;
+                while ((nl = buf.indexOf("\n\n")) >= 0) {
+                    const frame = buf.slice(0, nl);
+                    buf = buf.slice(nl + 2);
+                    const line = frame.split("\n").find((l) => l.startsWith("data:"));
+                    if (!line)
+                        continue; // heartbeat / comment
+                    try {
+                        const d = JSON.parse(line.slice(5).trim());
+                        if (d && typeof d.accountId === "string")
+                            opts.onChange(d.accountId, Array.isArray(d.domains) ? d.domains : undefined);
+                    }
+                    catch {
+                        /* non-json frame */
+                    }
+                }
+            }
+        }
+        catch {
+            /* network error / abort */
+        }
+        if (closed)
+            return;
+        const wait = backoff;
+        backoff = Math.min(backoff * 2, 30000);
+        setTimeout(connect, wait);
+    };
+    void connect();
+    return () => {
+        closed = true;
+        ctrl?.abort();
+    };
+}
+//# sourceMappingURL=ai-invalidation.js.map

package/dist/ai-invalidation.js.map

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

package/dist/contrast.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Accent/foreground contrast, WCAG 2.1 relative luminance (#307).
+ *
+ * WHY THIS EXISTS: the widget shipped `--aiw-accent-contrast: #fff`, correct
+ * against its own violet default (7.10:1) and never overridden by a single
+ * host. All three of ours pass a brand accent and none passes a contrast
+ * colour, so every accent-filled control rendered white on teal `#60C7C8` —
+ * **2.00:1**, against a 4.5:1 floor. Seventeen declarations, thirteen controls,
+ * four surfaces.
+ *
+ * A default cannot fix that, because the failing value IS the default. The
+ * pairing has to be DERIVED from whatever accent arrives — which also makes the
+ * widget safe to publish (#306), where we will not control the accent at all.
+ *
+ * No dependency on @sgiant/tokens on purpose: this file has to survive being
+ * extracted into a public package.
+ */
+/** The two foregrounds we choose between. Both are brand values, and both are
+ *  near enough to black/white to behave sensibly for an arbitrary accent a
+ *  third-party host passes. */
+export declare const CONTRAST_DARK = "#151D2F";
+export declare const CONTRAST_LIGHT = "#FCF7E3";
+/** WCAG 2.1 relative luminance. */
+export declare function relativeLuminance(hex: string): number | null;
+/** WCAG contrast ratio, 1–21. Null when either colour is unparseable. */
+export declare function contrastRatio(a: string, b: string): number | null;
+/**
+ * The foreground to use on a given accent: whichever of dark/light contrasts
+ * more. Returns null for anything it cannot parse — `color-mix()`, a CSS
+ * variable, `rebeccapurple` — so the caller leaves the host's own value alone
+ * instead of overwriting it with a guess.
+ *
+ * Measured on the accents this repo actually ships: teal → navy 8.41, amber →
+ * navy 8.73, orange → navy 5.98, and the violet default → cream 6.62. All four
+ * clear 4.5:1, which the host repo's contrast test asserts, so the
+ * next brand-colour change cannot quietly undo it.
+ */
+export declare function resolveAccentContrast(accent: string): string | null;
+/**
+ * Mix two hex colours in sRGB, the same way CSS `color-mix(in srgb, …)` does.
+ *
+ * Exists because the user's message bubble is not painted with the accent — it
+ * is painted with the accent mixed 76% into a near-black navy, and a foreground
+ * derived from the RAW accent is derived against the wrong background. Over the
+ * teal all three hosts pass, that bubble resolves to `#4a9d9e` and the sheet's
+ * literal `#fff` measures **3.18:1** on it: #307's defect, still live in the
+ * most-used element in the widget, because the fix was applied to the token and
+ * the bubble never read the token.
+ *
+ * The mix is computed HERE and handed to CSS as a resolved value, rather than
+ * computed here AND written as a `color-mix()` next door. Two implementations of
+ * one blend is how the foreground and the background drift apart, which is the
+ * whole bug again one level down.
+ *
+ * Null when either colour is unparseable — the caller must then leave whatever
+ * was there alone rather than guess, exactly as `resolveAccentContrast` does.
+ */
+export declare function mixSrgb(a: string, b: string, ratioA: number): string | null;
+/**
+ * The accent, adjusted until it is legible as TEXT on a given surface.
+ *
+ * `--aiw-accent` is a FILL colour. Twenty rules also use it as ink — links,
+ * hover states, the focused input, chips, KPI deltas, the menu icons, the
+ * active vote — and a fill is not an ink. Measured against the surfaces this
+ * sheet actually paints:
+ *
+ *   teal   #60C7C8 (what all three hosts pass)   2.00:1 on white,  9.05 on dark
+ *   violet #6d28d9 (the widget's own default)    7.10:1 on white,  2.55 on dark
+ *   amber  #FBAA34                               1.93:1 on white,  9.39 on dark
+ *
+ * So it is not "the teal is a bad accent". Every accent is illegible as ink on
+ * one of the two schemes; the widget's own default is the one that fails in the
+ * dark. Which scheme breaks depends only on where the accent sits between the
+ * two surfaces, and that is a property of the colour, not a mistake in it.
+ *
+ * The adjustment blends toward black or white — whichever the surface is
+ * further from — and returns the FIRST step that clears the floor, so the ink
+ * stays as close to the brand accent as legibility allows rather than jumping
+ * to a safe navy. Hue survives; some chroma does not.
+ *
+ * 5% steps because that is finer than the eye reads as a colour change and
+ * still terminates in twenty iterations. Null when the accent is unparseable —
+ * the caller leaves the token alone and the sheet's own default applies, which
+ * is the same contract as `resolveAccentContrast`.
+ */
+export declare function accentInk(accent: string, surface: string, target?: number): string | null;
+//# sourceMappingURL=contrast.d.ts.map

package/dist/contrast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contrast.d.ts","sourceRoot":"","sources":["../src/contrast.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;+BAE+B;AAC/B,eAAO,MAAM,aAAa,YAAY,CAAC;AACvC,eAAO,MAAM,cAAc,YAAY,CAAC;AAqBxC,mCAAmC;AACnC,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ5D;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKjE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKnE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAU3E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,MAAM,SAAM,GACX,MAAM,GAAG,IAAI,CAWf"}

package/dist/contrast.js

@@ -0,0 +1,151 @@
+/**
+ * Accent/foreground contrast, WCAG 2.1 relative luminance (#307).
+ *
+ * WHY THIS EXISTS: the widget shipped `--aiw-accent-contrast: #fff`, correct
+ * against its own violet default (7.10:1) and never overridden by a single
+ * host. All three of ours pass a brand accent and none passes a contrast
+ * colour, so every accent-filled control rendered white on teal `#60C7C8` —
+ * **2.00:1**, against a 4.5:1 floor. Seventeen declarations, thirteen controls,
+ * four surfaces.
+ *
+ * A default cannot fix that, because the failing value IS the default. The
+ * pairing has to be DERIVED from whatever accent arrives — which also makes the
+ * widget safe to publish (#306), where we will not control the accent at all.
+ *
+ * No dependency on @sgiant/tokens on purpose: this file has to survive being
+ * extracted into a public package.
+ */
+/** The two foregrounds we choose between. Both are brand values, and both are
+ *  near enough to black/white to behave sensibly for an arbitrary accent a
+ *  third-party host passes. */
+export const CONTRAST_DARK = "#151D2F"; // brand navy
+export const CONTRAST_LIGHT = "#FCF7E3"; // brand cream
+/** #rgb, #rrggbb, or #rrggbbaa → [r,g,b] 0-255. Null when unparseable — a
+ *  caller must then keep whatever it already had rather than guess. */
+function parseHex(hex) {
+    const h = hex.trim().replace(/^#/, "");
+    if (h.length === 3) {
+        const [r, g, b] = h.split("");
+        if (!/^[0-9a-f]{3}$/i.test(h))
+            return null;
+        return [parseInt(r + r, 16), parseInt(g + g, 16), parseInt(b + b, 16)];
+    }
+    if ((h.length === 6 || h.length === 8) && /^[0-9a-f]+$/i.test(h)) {
+        return [
+            parseInt(h.slice(0, 2), 16),
+            parseInt(h.slice(2, 4), 16),
+            parseInt(h.slice(4, 6), 16),
+        ];
+    }
+    return null;
+}
+/** WCAG 2.1 relative luminance. */
+export function relativeLuminance(hex) {
+    const rgb = parseHex(hex);
+    if (!rgb)
+        return null;
+    const [r, g, b] = rgb.map((c) => {
+        const s = c / 255;
+        return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+    });
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+/** WCAG contrast ratio, 1–21. Null when either colour is unparseable. */
+export function contrastRatio(a, b) {
+    const la = relativeLuminance(a);
+    const lb = relativeLuminance(b);
+    if (la === null || lb === null)
+        return null;
+    return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+/**
+ * The foreground to use on a given accent: whichever of dark/light contrasts
+ * more. Returns null for anything it cannot parse — `color-mix()`, a CSS
+ * variable, `rebeccapurple` — so the caller leaves the host's own value alone
+ * instead of overwriting it with a guess.
+ *
+ * Measured on the accents this repo actually ships: teal → navy 8.41, amber →
+ * navy 8.73, orange → navy 5.98, and the violet default → cream 6.62. All four
+ * clear 4.5:1, which the host repo's contrast test asserts, so the
+ * next brand-colour change cannot quietly undo it.
+ */
+export function resolveAccentContrast(accent) {
+    const dark = contrastRatio(accent, CONTRAST_DARK);
+    const light = contrastRatio(accent, CONTRAST_LIGHT);
+    if (dark === null || light === null)
+        return null;
+    return dark >= light ? CONTRAST_DARK : CONTRAST_LIGHT;
+}
+/**
+ * Mix two hex colours in sRGB, the same way CSS `color-mix(in srgb, …)` does.
+ *
+ * Exists because the user's message bubble is not painted with the accent — it
+ * is painted with the accent mixed 76% into a near-black navy, and a foreground
+ * derived from the RAW accent is derived against the wrong background. Over the
+ * teal all three hosts pass, that bubble resolves to `#4a9d9e` and the sheet's
+ * literal `#fff` measures **3.18:1** on it: #307's defect, still live in the
+ * most-used element in the widget, because the fix was applied to the token and
+ * the bubble never read the token.
+ *
+ * The mix is computed HERE and handed to CSS as a resolved value, rather than
+ * computed here AND written as a `color-mix()` next door. Two implementations of
+ * one blend is how the foreground and the background drift apart, which is the
+ * whole bug again one level down.
+ *
+ * Null when either colour is unparseable — the caller must then leave whatever
+ * was there alone rather than guess, exactly as `resolveAccentContrast` does.
+ */
+export function mixSrgb(a, b, ratioA) {
+    const pa = parseHex(a);
+    const pb = parseHex(b);
+    if (!pa || !pb)
+        return null;
+    const p = Math.min(1, Math.max(0, ratioA));
+    const chan = (i) => Math.round(pa[i] * p + pb[i] * (1 - p))
+        .toString(16)
+        .padStart(2, "0");
+    return `#${chan(0)}${chan(1)}${chan(2)}`;
+}
+/**
+ * The accent, adjusted until it is legible as TEXT on a given surface.
+ *
+ * `--aiw-accent` is a FILL colour. Twenty rules also use it as ink — links,
+ * hover states, the focused input, chips, KPI deltas, the menu icons, the
+ * active vote — and a fill is not an ink. Measured against the surfaces this
+ * sheet actually paints:
+ *
+ *   teal   #60C7C8 (what all three hosts pass)   2.00:1 on white,  9.05 on dark
+ *   violet #6d28d9 (the widget's own default)    7.10:1 on white,  2.55 on dark
+ *   amber  #FBAA34                               1.93:1 on white,  9.39 on dark
+ *
+ * So it is not "the teal is a bad accent". Every accent is illegible as ink on
+ * one of the two schemes; the widget's own default is the one that fails in the
+ * dark. Which scheme breaks depends only on where the accent sits between the
+ * two surfaces, and that is a property of the colour, not a mistake in it.
+ *
+ * The adjustment blends toward black or white — whichever the surface is
+ * further from — and returns the FIRST step that clears the floor, so the ink
+ * stays as close to the brand accent as legibility allows rather than jumping
+ * to a safe navy. Hue survives; some chroma does not.
+ *
+ * 5% steps because that is finer than the eye reads as a colour change and
+ * still terminates in twenty iterations. Null when the accent is unparseable —
+ * the caller leaves the token alone and the sheet's own default applies, which
+ * is the same contract as `resolveAccentContrast`.
+ */
+export function accentInk(accent, surface, target = 4.5) {
+    const surfaceLum = relativeLuminance(surface);
+    if (surfaceLum === null || parseHex(accent) === null)
+        return null;
+    const pole = surfaceLum > 0.5 ? "#000000" : "#ffffff";
+    for (let p = 1; p >= 0; p -= 0.05) {
+        const candidate = mixSrgb(accent, pole, p);
+        if (!candidate)
+            return null;
+        const ratio = contrastRatio(candidate, surface);
+        if (ratio !== null && ratio >= target)
+            return candidate;
+    }
+    return pole;
+}
+//# sourceMappingURL=contrast.js.map

package/dist/contrast.js.map

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

package/dist/directive.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The `[[tag:{json}]]` directive extractor the chat widget runs over every
+ * assistant reply.
+ *
+ * Lives in its own module because it is pure and because getting it wrong is
+ * VISIBLE: whatever this function fails to consume is shown to the user as raw
+ * text in the middle of a sentence. That makes it worth pinning down with
+ * tests, which the widget itself (imperative DOM, no harness) cannot be.
+ */
+export interface ParsedDirective<T> {
+    spec: T;
+    /** The message with this directive removed. */
+    stripped: string;
+    start: number;
+    /** Index just past everything consumed — the directive leaves no residue. */
+    end: number;
+}
+/**
+ * Pull the FIRST `[[tag:{json}]]` out of `text`.
+ *
+ * Forgiving by design, because the delimiters are the part a model gets wrong
+ * most often and every slip is shown to the user as raw punctuation:
+ *
+ *  - the JSON object is BRACE-MATCHED, string- and escape-aware, so a `}` or
+ *    `]]` inside a quoted caption cannot end it early;
+ *  - 0–2 trailing `]` are consumed, so `…}]]`, `…}]` and `…}` all parse;
+ *  - a surplus `}` before the brackets is consumed too. A model that closes one
+ *    brace too many is common, and it used to leave `}]]` sitting in the reply:
+ *    the matcher stopped at the REAL closing brace (correctly), then looked for
+ *    `]`, found `}`, and gave up — so the card rendered perfectly and the user
+ *    still saw `}]]` printed above it.
+ *
+ * Only ADJACENT residue is swallowed. Once a character is neither `}` nor `]`,
+ * consumption stops, so nothing the assistant actually wrote is eaten.
+ */
+export declare function parseJsonDirective<T>(text: string, tag: string): ParsedDirective<T> | null;
+//# sourceMappingURL=directive.d.ts.map

package/dist/directive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directive.d.ts","sourceRoot":"","sources":["../src/directive.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,IAAI,EAAE,CAAC,CAAC;IACR,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GACV,eAAe,CAAC,CAAC,CAAC,GAAG,IAAI,CA8C3B"}