sgiant-ai-widget 1.0.0

package/dist/specs.d.ts

@@ -0,0 +1,173 @@
+/**
+ * The directive vocabulary: what the model may emit inside `[[tag:{json}]]`,
+ * and the parsing that turns it into something a renderer can draw.
+ *
+ * Extracted from index.ts (#320) at zero leakage. This is the half of the
+ * widget's extension seam that #306 calls "a real extension point" — the model
+ * emits a directive, the host registers a renderer, the widget hands over the
+ * parsed JSON. A third party writing their own renderer needs these shapes,
+ * and needs to find them without reading 7000 lines.
+ *
+ * `stripDirectivesForReplay` lives here rather than beside the replay code
+ * because it is the same grammar read in the other direction: it removes
+ * exactly what this file defines.
+ */
+/** A data widget the assistant can render inline via `[[widget:{json}]]`. */
+export interface WidgetSpec {
+    /** "stat" | "kpis" | "list" | "table". Unknown kinds fall back to a list. */
+    kind?: string;
+    title?: string;
+    /** stat: the big value + caption + optional delta. */
+    value?: string | number;
+    caption?: string;
+    delta?: string;
+    /** kpis: tiles of {label,value}. */
+    items?: Array<{
+        label?: string;
+        value?: string | number;
+        delta?: string;
+    }>;
+    /** list: plain bullet lines. */
+    lines?: string[];
+    /** table: header columns + row cells. */
+    columns?: string[];
+    rows?: Array<Array<string | number>>;
+}
+/** A navigation suggestion the assistant emits via `[[navigate:{json}]]`. */
+export interface NavigateSpec {
+    path: string;
+    label?: string;
+}
+/** A dynamic HTML preview the assistant draws via `[[preview:{json}]]` — rendered
+ *  in a fully sandboxed iframe (no scripts, no same-origin) so arbitrary HTML+CSS
+ *  paints the real look but nothing can execute or reach out. */
+export interface PreviewSpec {
+    html: string;
+    title?: string;
+}
+/** An in-app action the assistant proposes via `[[action:{json}]]`. The host
+ *  maps `name` to a real operation; `confirm` (if set) requires user approval. */
+export interface ActionSpec {
+    name: string;
+    label?: string;
+    /** Confirmation prompt — when set, the user must approve before it runs. */
+    confirm?: string;
+    /** Opaque data passed to the host's onWidgetAction(name, data). */
+    data?: Record<string, string>;
+}
+/** Quick-reply chips the assistant offers via `[[chips:{json}]]` — tappable
+ *  answer options so the user picks instead of typing. Single-select sends on
+ *  tap; multi-select toggles + a Send button; `other` adds a "type your own"
+ *  chip. The chosen text is sent as a NORMAL message (history stays in order). */
+export interface ChipsSpec {
+    options: string[];
+    multi?: boolean;
+    other?: boolean;
+}
+/** Sentinel the assistant emits to ask the widget to render an email form. */
+export declare const LEAD_TOKEN = "[[collect-email]]";
+/** One field in an AI-rendered form directive. */
+export interface FormField {
+    name: string;
+    label?: string;
+    /** Kept in step with what `buildField` can actually draw — a spec allowed to
+     *  ask for a control the builder cannot render is a promise to the model that
+     *  the UI then breaks. */
+    type?: "text" | "email" | "number" | "textarea" | "select" | "checkbox" | "radio";
+    placeholder?: string;
+    required?: boolean;
+    options?: string[];
+}
+export interface FormSpec {
+    action: string;
+    title?: string;
+    fields: FormField[];
+    submit?: string;
+}
+/**
+ * A field the ASSISTANT asked the user to fill in on a proposal card.
+ *
+ * Declared by the proposal, never by the widget. A table of "which args are
+ * editable for which tool" hardcoded in the UI would mean the chat can only
+ * ever ask the questions the frontend was built to ask — a new tool, or a
+ * decision the model wants confirmed, would need a UI release. The model knows
+ * what it is unsure about; it says so, and the card renders it.
+ *
+ * Same shape as a `[[form:…]]` field, and built by the same `buildField`, so an
+ * input looks identical wherever the chat draws one.
+ */
+export interface ProposalField {
+    /** The proposal ARG this field overwrites on apply. */
+    arg: string;
+    label?: string;
+    type?: string;
+    placeholder?: string;
+    options?: string[];
+    required?: boolean;
+}
+/**
+ * A control `buildField` produced, plus how to read its answer.
+ *
+ * The reader is part of the return value because "what the user chose" is not
+ * `.value` for every control type — a checkbox is `.checked`, a radio group is
+ * whichever of its inputs is checked — and every caller wants the same thing: a
+ * string to put in the payload.
+ */
+export interface BuiltField {
+    /** Append THIS — the control, or the wrapper a labelled/grouped one needs. */
+    node: HTMLElement;
+    read: () => string;
+    /** The control draws its own caption; a caller adding one would double it. */
+    selfLabelled?: boolean;
+}
+/** Truthiness for a prefilled checkbox — model output, so accept the obvious
+ *  spellings rather than demanding exactly `"true"`. */
+export declare function isTruthyValue(v: string | undefined): boolean;
+/** A proposal arg a field can be PREFILLED from: anything JSON-primitive, which
+ *  is everything with one obvious rendering. Objects/arrays have none, and
+ *  null/undefined mean the assistant proposed nothing for that arg. */
+export declare function isPrimitiveArg(v: unknown): v is string | number | boolean;
+/** Read the fields off a proposal frame, defensively — this is model output. */
+export declare function proposalFields(raw: unknown): ProposalField[];
+/** Pull a `[[form:{json}]]` directive out of assistant text, if present. Uses
+ *  the shared brace-matching extractor, then validates the form shape. */
+export declare function parseFormDirective(text: string): {
+    spec: FormSpec;
+    stripped: string;
+} | null;
+/**
+ * REPLAY view of a stored message: strip every interactive directive (which the
+ * live turn already rendered as buttons/forms) so a reopened conversation shows
+ * clean prose instead of raw `[[navigate:…]]` / `[[form:…]]` code, with a short
+ * INERT note per directive (no re-execution). Used by the history/thread
+ * restore path; live turns still render the real interactive widgets.
+ */
+export declare function stripDirectivesForReplay(text: string): {
+    clean: string;
+    notes: string[];
+    navs: NavigateSpec[];
+    uis: unknown[];
+};
+/**
+ * Build one editable control for a proposal form, plus how to READ it back.
+ *
+ * Moved here from index.ts (#320) with ZERO closure dependencies — the whole
+ * function reaches only `el`, `PREFIX`, and this file's own `BuiltField` and
+ * `isTruthyValue`. It sat in the 6000-line closure purely because that is
+ * where it was typed; nothing about it was ever widget state.
+ *
+ * `read` is the point of the return shape: every control answers as a STRING
+ * whatever it was drawn as, because the submit path posts a flat
+ * `Record<string, string>`. A checkbox that returned a boolean would be the
+ * one field in the form with a different contract.
+ */
+export declare function buildField(field: {
+    name: string;
+    type?: string;
+    label?: string;
+    placeholder?: string;
+    options?: string[];
+    required?: boolean;
+    value?: string;
+}): BuiltField;
+//# sourceMappingURL=specs.d.ts.map

package/dist/specs.d.ts.map

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

package/dist/specs.js

@@ -0,0 +1,231 @@
+/**
+ * The directive vocabulary: what the model may emit inside `[[tag:{json}]]`,
+ * and the parsing that turns it into something a renderer can draw.
+ *
+ * Extracted from index.ts (#320) at zero leakage. This is the half of the
+ * widget's extension seam that #306 calls "a real extension point" — the model
+ * emits a directive, the host registers a renderer, the widget hands over the
+ * parsed JSON. A third party writing their own renderer needs these shapes,
+ * and needs to find them without reading 7000 lines.
+ *
+ * `stripDirectivesForReplay` lives here rather than beside the replay code
+ * because it is the same grammar read in the other direction: it removes
+ * exactly what this file defines.
+ */
+import { parseJsonDirective } from "./directive.js";
+import { el } from "./dom.js";
+import { PREFIX } from "./prefix.js";
+/** Sentinel the assistant emits to ask the widget to render an email form. */
+export const LEAD_TOKEN = "[[collect-email]]";
+/** Truthiness for a prefilled checkbox — model output, so accept the obvious
+ *  spellings rather than demanding exactly `"true"`. */
+export function isTruthyValue(v) {
+    return ["true", "1", "yes", "on"].includes((v ?? "").trim().toLowerCase());
+}
+/** A proposal arg a field can be PREFILLED from: anything JSON-primitive, which
+ *  is everything with one obvious rendering. Objects/arrays have none, and
+ *  null/undefined mean the assistant proposed nothing for that arg. */
+export function isPrimitiveArg(v) {
+    return (typeof v === "string" || typeof v === "number" || typeof v === "boolean");
+}
+/** Read the fields off a proposal frame, defensively — this is model output. */
+export function proposalFields(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .filter((f) => Boolean(f) &&
+        typeof f === "object" &&
+        typeof f.arg === "string" &&
+        Boolean(f.arg))
+        .slice(0, 6);
+}
+/** Pull a `[[form:{json}]]` directive out of assistant text, if present. Uses
+ *  the shared brace-matching extractor, then validates the form shape. */
+export function parseFormDirective(text) {
+    const r = parseJsonDirective(text, "form");
+    if (!r)
+        return null;
+    const { spec } = r;
+    if (!spec || typeof spec.action !== "string" || !Array.isArray(spec.fields))
+        return null;
+    return r;
+}
+/**
+ * REPLAY view of a stored message: strip every interactive directive (which the
+ * live turn already rendered as buttons/forms) so a reopened conversation shows
+ * clean prose instead of raw `[[navigate:…]]` / `[[form:…]]` code, with a short
+ * INERT note per directive (no re-execution). Used by the history/thread
+ * restore path; live turns still render the real interactive widgets.
+ */
+export function stripDirectivesForReplay(text) {
+    let t = text;
+    const notes = [];
+    const uis = [];
+    // Navigation is idempotent and side-effect-free, so on replay we hand it back
+    // to be re-rendered as a REAL clickable chip rather than flattened to an inert
+    // note — otherwise every "Open <page>" the assistant offered goes dead the
+    // moment the thread reloads (which send() does after each turn for canonical
+    // ids). This is the true cause of #111: the model DID emit [[navigate]], the
+    // restore path is what killed it.
+    const navs = [];
+    for (let i = 0; i < 8; i++) {
+        const w = parseJsonDirective(t, "navigate");
+        if (!w)
+            break;
+        t = w.stripped;
+        if (w.spec.path)
+            navs.push(w.spec);
+        else
+            notes.push(`↗ ${w.spec.label || "Open page"}`);
+    }
+    for (let i = 0; i < 8; i++) {
+        const w = parseJsonDirective(t, "action");
+        if (!w)
+            break;
+        t = w.stripped;
+        notes.push(`• ${w.spec.label || w.spec.name}`);
+    }
+    for (let i = 0; i < 8; i++) {
+        const w = parseJsonDirective(t, "widget");
+        if (!w)
+            break;
+        t = w.stripped;
+        notes.push(`▦ ${w.spec.title || "widget"}`);
+    }
+    // Composed UI cards are handed BACK to be re-drawn, not flattened to a note.
+    // A card is the substance of the turn, not a decoration on it: a client who
+    // reopens the conversation tomorrow to look at the scenes they were approving
+    // would otherwise find "▦ card" where the scenes had been. Re-drawing is safe
+    // because every button on a card requires a click — nothing here can run by
+    // itself on restore.
+    for (let i = 0; i < 4; i++) {
+        const u = parseJsonDirective(t, "ui");
+        if (!u)
+            break;
+        t = u.stripped;
+        uis.push(u.spec);
+    }
+    for (let i = 0; i < 3; i++) {
+        const p = parseJsonDirective(t, "preview");
+        if (!p)
+            break;
+        t = p.stripped;
+        notes.push(`[preview] ${p.spec.title || "Preview"}`);
+    }
+    for (let i = 0; i < 4; i++) {
+        const c = parseJsonDirective(t, "chips");
+        if (!c)
+            break;
+        t = c.stripped;
+        notes.push("💬 options offered");
+    }
+    const f = parseFormDirective(t);
+    if (f) {
+        t = f.stripped;
+        notes.push(`📝 ${f.spec.title || "Form"} — submitted`);
+    }
+    if (t.includes(LEAD_TOKEN)) {
+        t = t.replace(LEAD_TOKEN, "").trim();
+        notes.push("📝 Form — submitted");
+    }
+    return { clean: t, notes, navs, uis };
+}
+/**
+ * Build one editable control for a proposal form, plus how to READ it back.
+ *
+ * Moved here from index.ts (#320) with ZERO closure dependencies — the whole
+ * function reaches only `el`, `PREFIX`, and this file's own `BuiltField` and
+ * `isTruthyValue`. It sat in the 6000-line closure purely because that is
+ * where it was typed; nothing about it was ever widget state.
+ *
+ * `read` is the point of the return shape: every control answers as a STRING
+ * whatever it was drawn as, because the submit path posts a flat
+ * `Record<string, string>`. A checkbox that returned a boolean would be the
+ * one field in the form with a different contract.
+ */
+export function buildField(field) {
+    const type = field.type ?? "text";
+    // Boolean/choice controls carry their own caption — a bare 16px box with
+    // the label somewhere above it reads as decoration, not as a question.
+    if (type === "checkbox") {
+        const row = el("label", `${PREFIX}-field-check`);
+        const box = el("input", `${PREFIX}-check`);
+        box.type = "checkbox";
+        box.checked = isTruthyValue(field.value);
+        if (field.required)
+            box.required = true;
+        row.appendChild(box);
+        const cap = el("span", `${PREFIX}-field-check-label`);
+        cap.textContent = field.label ?? field.placeholder ?? field.name;
+        row.appendChild(cap);
+        // Stringified so a field's answer is always a string, whatever it was
+        // drawn as — the submit path posts a flat Record<string,string>.
+        return {
+            node: row,
+            selfLabelled: true,
+            read: () => (box.checked ? "true" : "false"),
+        };
+    }
+    if (type === "radio" && field.options?.length) {
+        const group = el("div", `${PREFIX}-field-group`);
+        // The `name` attribute is what makes radios mutually exclusive, so it has
+        // to be unique per rendered group — two proposal cards asking the same
+        // question would otherwise fight over one selection.
+        const groupName = `${PREFIX}-${field.name}-${Math.random().toString(36).slice(2, 9)}`;
+        for (const o of field.options) {
+            const row = el("label", `${PREFIX}-field-check`);
+            const radio = el("input", `${PREFIX}-check`);
+            radio.type = "radio";
+            radio.name = groupName;
+            radio.value = o;
+            // Required propagates to the inputs (one required radio makes the whole
+            // group required). It was dropped here, so a required choice reported
+            // itself as answered while nothing was selected.
+            if (field.required)
+                radio.required = true;
+            if (o === field.value)
+                radio.checked = true;
+            row.appendChild(radio);
+            const cap = el("span", `${PREFIX}-field-check-label`);
+            cap.textContent = o;
+            row.appendChild(cap);
+            group.appendChild(row);
+        }
+        return {
+            node: group,
+            read: () => group.querySelector("input:checked")?.value ?? "",
+        };
+    }
+    let input;
+    if (type === "textarea") {
+        input = el("textarea", `${PREFIX}-field`);
+    }
+    else if (type === "select") {
+        const sel = el("select", `${PREFIX}-field`);
+        for (const o of field.options ?? []) {
+            const opt = document.createElement("option");
+            opt.value = o;
+            opt.textContent = o;
+            sel.appendChild(opt);
+        }
+        input = sel;
+    }
+    else {
+        const i = el("input", `${PREFIX}-field`);
+        i.type = type === "number" ? "number" : type;
+        input = i;
+    }
+    if ("placeholder" in input && field.placeholder)
+        input.placeholder = field.label
+            ? `${field.label} — ${field.placeholder}`
+            : field.placeholder;
+    else if ("placeholder" in input && field.label)
+        input.placeholder = field.label;
+    if (field.required)
+        input.required = true;
+    // Prefilled: the card hands back a value the user can accept or rewrite.
+    if (field.value !== undefined)
+        input.value = field.value;
+    return { node: input, read: () => input.value.trim() };
+}
+//# sourceMappingURL=specs.js.map

package/dist/specs.js.map

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

package/dist/storage.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Every persisted value the widget owns, and the two rules that govern all of
+ * them.
+ *
+ * Extracted from index.ts (#320). Storage was not one region of that file — it
+ * was 33 `localStorage` touches spread across 8 key-scoped concerns, from the
+ * draft textarea to the launcher position to the advanced-pane width. Each site
+ * re-implemented the same two rules, which is how they drifted:
+ *
+ *   1. AN EMPTY KEY MEANS PERSISTENCE IS OFF. Most keys are derived from
+ *      `opts.persistKey`, which is optional: no persistKey, no writing to a
+ *      visitor's browser. That was eight separate `if (!key) return` guards.
+ *   2. BLOCKED STORAGE IS NON-FATAL. Private windows, cleared site data and
+ *      "block third-party cookies" all throw on access rather than returning
+ *      null, so every read and every write needs a try/catch. That was ten
+ *      of them, each with its own comment saying the same thing.
+ *
+ * THE ONE PLACE THOSE RULES ARE NOT UNIFORM is the point of collecting them.
+ * `hasOpenedBefore` returns TRUE when storage is unreadable, while every other
+ * flag defaults to false. That is deliberate — a returning reader should get
+ * the quiet pebble, not the first-visit pill on every single page load — but in
+ * index.ts it was one `return true` inside one of ten identical-looking catch
+ * blocks, indistinguishable from a typo. Here it is an argument with a name.
+ *
+ * These helpers take the key rather than closing over it, so they are callable
+ * from anywhere and testable without constructing a widget.
+ */
+/**
+ * A key that names a real slot.
+ *
+ * "Persistence is off" is spelled TWO ways in the caller — `null` for the five
+ * keys derived from `opts.persistKey`, `""` for the two derived from the
+ * advanced pane. Neither spelling is wrong and unifying them in index.ts would
+ * be a behaviour-free diff across a 5800-line file, so this is the one place
+ * that has to know both, and the only place that should.
+ */
+type StorageKey = string | null | undefined;
+/**
+ * Read a string. Returns `fallback` when the key is off, absent, or storage is
+ * unreadable — the three cases callers have never needed to tell apart.
+ */
+export declare function readItem(key: StorageKey, fallback?: string): string;
+/** Write a string, or REMOVE the key when given an empty value or null. */
+export declare function writeItem(key: StorageKey, value: string | null): void;
+/**
+ * Read a `"1"`/`"0"` flag.
+ *
+ * ABSENT AND UNREADABLE ARE DIFFERENT STATES, and collapsing them is a bug this
+ * function was written with and had to have removed. A key that is simply not
+ * set means "false" — the flag has never been turned on. `whenUnavailable` is
+ * only for the case where storage THREW, i.e. the answer is unknowable rather
+ * than no.
+ *
+ * The distinction is invisible in four of the five callers, whose answer is
+ * false either way. In the fifth it inverts the first-visit experience: a
+ * first-ever visitor has no `sg_ayca_opened` key, and answering "unavailable"
+ * there would greet them as a returning reader and suppress the pill they are
+ * supposed to see.
+ */
+export declare function readFlag(key: StorageKey, whenUnavailable?: boolean): boolean;
+/** Write a `"1"`/`"0"` flag. */
+export declare function writeFlag(key: StorageKey, on: boolean): void;
+/**
+ * Read JSON and hand it to a validator before returning it.
+ *
+ * The validator is required rather than optional on purpose: everything in
+ * localStorage was written by a PREVIOUS BUILD of this widget and may not match
+ * the current shape. Two of the callers here already learned that — the tracked
+ * jobs list deliberately accepts entries with no `kind` because a build that
+ * predates the field wrote them, and dropping those would lose the card for
+ * work still running across a deploy.
+ */
+export declare function readJson<T>(key: StorageKey, isValid: (value: unknown) => value is T): T | null;
+/** Write JSON, or REMOVE the key when given null. */
+export declare function writeJson(key: StorageKey, value: unknown | null): void;
+export {};
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;GAQG;AACH,KAAK,UAAU,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAG5C;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,SAAK,GAAG,MAAM,CAO/D;AAED,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAQrE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,UAAU,EAAE,eAAe,UAAQ,GAAG,OAAO,CAO1E;AAED,gCAAgC;AAChC,wBAAgB,SAAS,CAAC,GAAG,EAAE,UAAU,EAAE,EAAE,EAAE,OAAO,GAAG,IAAI,CAE5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,GACtC,CAAC,GAAG,IAAI,CAUV;AAED,qDAAqD;AACrD,wBAAgB,SAAS,CAAC,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,GAAG,IAAI,CAQtE"}

package/dist/storage.js

@@ -0,0 +1,124 @@
+/**
+ * Every persisted value the widget owns, and the two rules that govern all of
+ * them.
+ *
+ * Extracted from index.ts (#320). Storage was not one region of that file — it
+ * was 33 `localStorage` touches spread across 8 key-scoped concerns, from the
+ * draft textarea to the launcher position to the advanced-pane width. Each site
+ * re-implemented the same two rules, which is how they drifted:
+ *
+ *   1. AN EMPTY KEY MEANS PERSISTENCE IS OFF. Most keys are derived from
+ *      `opts.persistKey`, which is optional: no persistKey, no writing to a
+ *      visitor's browser. That was eight separate `if (!key) return` guards.
+ *   2. BLOCKED STORAGE IS NON-FATAL. Private windows, cleared site data and
+ *      "block third-party cookies" all throw on access rather than returning
+ *      null, so every read and every write needs a try/catch. That was ten
+ *      of them, each with its own comment saying the same thing.
+ *
+ * THE ONE PLACE THOSE RULES ARE NOT UNIFORM is the point of collecting them.
+ * `hasOpenedBefore` returns TRUE when storage is unreadable, while every other
+ * flag defaults to false. That is deliberate — a returning reader should get
+ * the quiet pebble, not the first-visit pill on every single page load — but in
+ * index.ts it was one `return true` inside one of ten identical-looking catch
+ * blocks, indistinguishable from a typo. Here it is an argument with a name.
+ *
+ * These helpers take the key rather than closing over it, so they are callable
+ * from anywhere and testable without constructing a widget.
+ */
+const live = (key) => Boolean(key);
+/**
+ * Read a string. Returns `fallback` when the key is off, absent, or storage is
+ * unreadable — the three cases callers have never needed to tell apart.
+ */
+export function readItem(key, fallback = "") {
+    if (!live(key))
+        return fallback;
+    try {
+        return localStorage.getItem(key) ?? fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+/** Write a string, or REMOVE the key when given an empty value or null. */
+export function writeItem(key, value) {
+    if (!live(key))
+        return;
+    try {
+        if (value)
+            localStorage.setItem(key, value);
+        else
+            localStorage.removeItem(key);
+    }
+    catch {
+        /* storage full or blocked — the value just does not persist */
+    }
+}
+/**
+ * Read a `"1"`/`"0"` flag.
+ *
+ * ABSENT AND UNREADABLE ARE DIFFERENT STATES, and collapsing them is a bug this
+ * function was written with and had to have removed. A key that is simply not
+ * set means "false" — the flag has never been turned on. `whenUnavailable` is
+ * only for the case where storage THREW, i.e. the answer is unknowable rather
+ * than no.
+ *
+ * The distinction is invisible in four of the five callers, whose answer is
+ * false either way. In the fifth it inverts the first-visit experience: a
+ * first-ever visitor has no `sg_ayca_opened` key, and answering "unavailable"
+ * there would greet them as a returning reader and suppress the pill they are
+ * supposed to see.
+ */
+export function readFlag(key, whenUnavailable = false) {
+    if (!live(key))
+        return false;
+    try {
+        return localStorage.getItem(key) === "1";
+    }
+    catch {
+        return whenUnavailable;
+    }
+}
+/** Write a `"1"`/`"0"` flag. */
+export function writeFlag(key, on) {
+    writeItem(key, on ? "1" : "0");
+}
+/**
+ * Read JSON and hand it to a validator before returning it.
+ *
+ * The validator is required rather than optional on purpose: everything in
+ * localStorage was written by a PREVIOUS BUILD of this widget and may not match
+ * the current shape. Two of the callers here already learned that — the tracked
+ * jobs list deliberately accepts entries with no `kind` because a build that
+ * predates the field wrote them, and dropping those would lose the card for
+ * work still running across a deploy.
+ */
+export function readJson(key, isValid) {
+    if (!live(key))
+        return null;
+    try {
+        const raw = localStorage.getItem(key);
+        if (!raw)
+            return null;
+        const parsed = JSON.parse(raw);
+        return isValid(parsed) ? parsed : null;
+    }
+    catch {
+        return null; // corrupt, or unreadable — either way, start fresh
+    }
+}
+/** Write JSON, or REMOVE the key when given null. */
+export function writeJson(key, value) {
+    if (!live(key))
+        return;
+    try {
+        if (value === null)
+            localStorage.removeItem(key);
+        else
+            localStorage.setItem(key, JSON.stringify(value));
+    }
+    catch {
+        /* storage full or blocked — non-fatal */
+    }
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAYH,MAAM,IAAI,GAAG,CAAC,GAAe,EAAiB,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;AAE9D;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAe,EAAE,QAAQ,GAAG,EAAE;IACrD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAC;IAChC,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,QAAQ,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,SAAS,CAAC,GAAe,EAAE,KAAoB;IAC7D,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO;IACvB,IAAI,CAAC;QACH,IAAI,KAAK;YAAE,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;;YACvC,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,+DAA+D;IACjE,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAe,EAAE,eAAe,GAAG,KAAK;IAC/D,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7B,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,eAAe,CAAC;IACzB,CAAC;AACH,CAAC;AAED,gCAAgC;AAChC,MAAM,UAAU,SAAS,CAAC,GAAe,EAAE,EAAW;IACpD,SAAS,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CACtB,GAAe,EACf,OAAuC;IAEvC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC;QACtB,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxC,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC,CAAC,mDAAmD;IAClE,CAAC;AACH,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,SAAS,CAAC,GAAe,EAAE,KAAqB;IAC9D,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO;IACvB,IAAI,CAAC;QACH,IAAI,KAAK,KAAK,IAAI;YAAE,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;;YAC5C,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,yCAAyC;IAC3C,CAAC;AACH,CAAC"}

package/dist/styles.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Does the page around us define the PLATFORM's control variables?
+ *
+ * When the widget is mounted inside one of our own apps, `--input` / `--ring` /
+ * `--card` / … are already on `<html>` (set by the host's own stylesheet), and
+ * a text field in chat should be the same object as a text field on the page
+ * behind it — same border, same focus ring, same radius, flipping together when
+ * the app toggles `.dark`. When the widget is embedded on a customer's site,
+ * none of that exists and it must fall back to its own `--aiw-*` palette.
+ *
+ * The check is deliberately shape-based, not merely presence-based: `--input`
+ * is a plausible name for anyone to invent, but our tokens are HSL COMPONENTS
+ * ("220 9% 85%") so they can be used with an alpha. A site whose `--input` is
+ * `#fff` fails the test and we leave its page alone — the failure mode of
+ * guessing wrong here is an unreadable chat form on someone else's website.
+ */
+/**
+ * The near-black the user bubble mixes the accent into.
+ *
+ * Exported because `index.ts` derives that bubble's foreground against the
+ * RESULT of the mix, not against the accent (#307 one level down: over the teal
+ * all three hosts pass, the bubble is `#4a9d9e` and the old literal `#fff` was
+ * 3.18:1). Two copies of this number would put the derivation and the paint on
+ * different backgrounds, which is the same bug again.
+ */
+export declare const USER_BUBBLE_INK = "#04191b";
+export declare function hostDefinesPlatformTokens(): boolean;
+export declare function injectStyles(side: "left" | "right"): void;
+//# sourceMappingURL=styles.d.ts.map