sgiant-ai-widget 1.0.0

package/dist/directive.js

@@ -0,0 +1,87 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function parseJsonDirective(text, tag) {
+    const open = `[[${tag}:`;
+    const start = text.indexOf(open);
+    if (start < 0)
+        return null;
+    const braceStart = text.indexOf("{", start + open.length);
+    if (braceStart < 0)
+        return null;
+    // Walk the JSON object, tracking string state, to find its true closing brace.
+    let depth = 0;
+    let inStr = false;
+    let esc = false;
+    let end = -1;
+    for (let i = braceStart; i < text.length; i++) {
+        const ch = text[i];
+        if (inStr) {
+            if (esc)
+                esc = false;
+            else if (ch === "\\")
+                esc = true;
+            else if (ch === '"')
+                inStr = false;
+        }
+        else if (ch === '"')
+            inStr = true;
+        else if (ch === "{")
+            depth++;
+        else if (ch === "}") {
+            depth--;
+            if (depth === 0) {
+                end = i;
+                break;
+            }
+        }
+    }
+    if (end < 0)
+        return null;
+    try {
+        const spec = JSON.parse(text.slice(braceStart, end + 1));
+        let after = end + 1;
+        // Surplus closing braces the model added past the object's real end.
+        // Bounded so a genuine `}` in following prose is never swallowed wholesale.
+        let extraBraces = 0;
+        while (text[after] === "}" && extraBraces < 3) {
+            after++;
+            extraBraces++;
+        }
+        // Then the closing brackets — 0, 1 or 2.
+        if (text[after] === "]")
+            after++;
+        if (text[after] === "]")
+            after++;
+        const stripped = (text.slice(0, start) + text.slice(after)).trim();
+        return { spec, stripped, start, end: after };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=directive.js.map

package/dist/directive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directive.js","sourceRoot":"","sources":["../src/directive.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAWH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAY,EACZ,GAAW;IAEX,MAAM,IAAI,GAAG,KAAK,GAAG,GAAG,CAAC;IACzB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3B,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1D,IAAI,UAAU,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAChC,+EAA+E;IAC/E,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,IAAI,GAAG,GAAG,KAAK,CAAC;IAChB,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,UAAU,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACnB,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,GAAG;gBAAE,GAAG,GAAG,KAAK,CAAC;iBAChB,IAAI,EAAE,KAAK,IAAI;gBAAE,GAAG,GAAG,IAAI,CAAC;iBAC5B,IAAI,EAAE,KAAK,GAAG;gBAAE,KAAK,GAAG,KAAK,CAAC;QACrC,CAAC;aAAM,IAAI,EAAE,KAAK,GAAG;YAAE,KAAK,GAAG,IAAI,CAAC;aAC/B,IAAI,EAAE,KAAK,GAAG;YAAE,KAAK,EAAE,CAAC;aACxB,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACpB,KAAK,EAAE,CAAC;YACR,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;gBAChB,GAAG,GAAG,CAAC,CAAC;gBACR,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IACD,IAAI,GAAG,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,GAAG,GAAG,CAAC,CAAC,CAAM,CAAC;QAC9D,IAAI,KAAK,GAAG,GAAG,GAAG,CAAC,CAAC;QACpB,qEAAqE;QACrE,4EAA4E;QAC5E,IAAI,WAAW,GAAG,CAAC,CAAC;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;YAC9C,KAAK,EAAE,CAAC;YACR,WAAW,EAAE,CAAC;QAChB,CAAC;QACD,yCAAyC;QACzC,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG;YAAE,KAAK,EAAE,CAAC;QACjC,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG;YAAE,KAAK,EAAE,CAAC;QACjC,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACnE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/dom.d.ts

@@ -0,0 +1,83 @@
+/** One decoded SSE frame. Lives here because `parseLine` produces it and
+ *  nothing upstream of the parser has an opinion about its shape. */
+export interface StreamFrame {
+    type?: string;
+    text?: string;
+    d?: string;
+    threadId?: string;
+    message?: string;
+    /** render_chart widget frame (analytics lane): spec = model args, rows = data. */
+    spec?: {
+        title?: string;
+        chartType?: string;
+    };
+    rows?: unknown;
+    /** Optional prior-period rows for the same chart (comparison overlay). */
+    comparisonRows?: unknown;
+    /** question frame — the assistant asking the human to DECIDE (see WsQuestion). */
+    questionId?: string;
+    prompt?: string;
+    context?: string;
+    options?: Array<{
+        id: string;
+        label: string;
+        description?: string;
+    }>;
+    multi?: boolean;
+    critical?: boolean;
+    /** activity frame — a live agent process step (running → ok/error). */
+    callId?: string;
+    name?: string;
+    label?: string;
+    status?: string;
+    /** tool_proposal frame — a confirm-gated write tool's args. */
+    args?: unknown;
+    /** tool_proposal frame — the AiArtifact the runner persisted for a
+     *  dashboard/template write, which is the ONLY handle its REST apply takes.
+     *  The runner has always emitted this; nothing here read it, so
+     *  `apply_dashboard` and `save_template` rendered a confirm card whose Apply
+     *  could only reach `throw new Error("Unsupported action")`. */
+    artifactId?: string;
+    /** usage frame — per-turn token counts (drives the session meter). */
+    inputTokens?: number;
+    outputTokens?: number;
+    /** quota frame — the free visitor allowance snapshot. */
+    granted?: number;
+    used?: number;
+    remaining?: number;
+    exhausted?: boolean;
+    /** meta frame — staff-only "model" chip: which model/agent runs the turn. */
+    isStaff?: boolean;
+    modelLabel?: string;
+    /** done frame — the persisted id of the turn's final assistant message, and
+     *  the model that wrote it. Absent when the turn persisted nothing. */
+    messageId?: string;
+    model?: string;
+}
+/** Parse one stream line — tolerates `data: ` SSE prefix and bare NDJSON. */
+export declare function parseLine(line: string): StreamFrame | null;
+/** Chip glyph per attachment kind — a clip showing the document icon would read
+ *  as "we did not understand your file". */
+export declare function attIcon(kind: string): string;
+export declare function el(tag: string, cls: string): HTMLElement;
+/** Coarse "when" bucket for grouping past conversations (Today / Yesterday / …). */
+/** Relative-time group for a timestamp — returns a WIDGET_LABELS key so the
+ *  caller resolves the localized separator text via L(). */
+export declare function relBucket(iso: string): "bucketToday" | "bucketYesterday" | "bucketWeek" | "bucketMonth" | "bucketOlder";
+/** Short relative label, e.g. "3h ago", "2w ago" — falls back to a date. */
+export declare function relTime(iso: string): string;
+/** Hide raw markdown control marks from a streamed chunk so the user reads clean
+ *  text WHILE the bot types (the real markdown renders once at the end). Light +
+ *  per-chunk — it only needs to look clean for the moment it streams. */
+export declare function maskMarkdown(s: string): string;
+/** Escape text for the few places we build innerHTML (nav button label). */
+export declare function escapeHtml(s: string): string;
+/** Wrap a bare HTML fragment in a minimal document so a preview always renders
+ *  sanely; a full document is used as-is. */
+export declare function wrapPreviewHtml(html: string): string;
+export declare function addMsg(log: HTMLElement, role: "user" | "assistant", text: string, attachments?: {
+    kind: string;
+    filename: string;
+    contentType: string;
+}[]): HTMLElement;
+//# sourceMappingURL=dom.d.ts.map

package/dist/dom.d.ts.map

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

package/dist/dom.js

@@ -0,0 +1,146 @@
+/**
+ * DOM construction and the small formatters around it.
+ *
+ * These nine helpers sat at the bottom of index.ts, below the 6,143-line
+ * `createAiChatWidget` closure and outside it — module-level all along, and
+ * used from inside it 240+ times (`el` alone has 215 call sites). Being outside
+ * the closure is what makes them the one seam in #320 that separates without a
+ * design decision: they capture nothing, so moving them is a move and not a
+ * refactor.
+ *
+ * Nothing here may reach back into the widget. If one of these ever needs
+ * widget state, it belongs in the closure or behind an explicit parameter — a
+ * helper that quietly grows a dependency on its caller is how the file got to
+ * 7,000 lines in the first place.
+ */
+import { PREFIX } from "./prefix.js";
+/** Parse one stream line — tolerates `data: ` SSE prefix and bare NDJSON. */
+export function parseLine(line) {
+    if (!line)
+        return null;
+    let json = line;
+    if (json.startsWith("data:"))
+        json = json.slice(5).trim();
+    if (!json || json === "[DONE]")
+        return null;
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+}
+/** Chip glyph per attachment kind — a clip showing the document icon would read
+ *  as "we did not understand your file". */
+export function attIcon(kind) {
+    if (kind === "image")
+        return "🖼";
+    if (kind === "video")
+        return "🎬";
+    if (kind === "audio")
+        return "🎵";
+    return "📄";
+}
+export function el(tag, cls) {
+    const node = document.createElement(tag);
+    node.className = cls;
+    // Every button gets the focus base HERE rather than at its 40 call sites
+    // (#308). Enumerating the call sites is the wrong shape — the list falls
+    // behind the code the first time someone adds a control, which is exactly how
+    // the widget ended up with forty buttons and no designed focus state. A
+    // button created after this change is covered without anyone remembering.
+    if (tag === "button")
+        node.classList.add(`${PREFIX}-btn`);
+    return node;
+}
+/** Coarse "when" bucket for grouping past conversations (Today / Yesterday / …). */
+/** Relative-time group for a timestamp — returns a WIDGET_LABELS key so the
+ *  caller resolves the localized separator text via L(). */
+export function relBucket(iso) {
+    const d = new Date(iso);
+    if (isNaN(d.getTime()))
+        return "bucketOlder";
+    const now = new Date();
+    const startToday = new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime();
+    const day = 86400000;
+    const t = d.getTime();
+    if (t >= startToday)
+        return "bucketToday";
+    if (t >= startToday - day)
+        return "bucketYesterday";
+    if (t >= startToday - 6 * day)
+        return "bucketWeek";
+    if (t >= startToday - 29 * day)
+        return "bucketMonth";
+    return "bucketOlder";
+}
+/** Short relative label, e.g. "3h ago", "2w ago" — falls back to a date. */
+export function relTime(iso) {
+    const d = new Date(iso);
+    if (isNaN(d.getTime()))
+        return "";
+    const diff = Date.now() - d.getTime();
+    const min = 60000;
+    const hr = 3600000;
+    const day = 86400000;
+    const wk = 7 * day;
+    if (diff < hr)
+        return `${Math.max(1, Math.floor(diff / min))}m ago`;
+    if (diff < day)
+        return `${Math.floor(diff / hr)}h ago`;
+    if (diff < wk)
+        return `${Math.floor(diff / day)}d ago`;
+    if (diff < 30 * day)
+        return `${Math.floor(diff / wk)}w ago`;
+    return d.toLocaleDateString();
+}
+/** Hide raw markdown control marks from a streamed chunk so the user reads clean
+ *  text WHILE the bot types (the real markdown renders once at the end). Light +
+ *  per-chunk — it only needs to look clean for the moment it streams. */
+export function maskMarkdown(s) {
+    return s
+        .replace(/`+/g, "") // code ticks
+        .replace(/[*~]/g, "") // bold / italic / strike markers
+        .replace(/^#{1,6}\s*/gm, "") // heading hashes
+        .replace(/^\s{0,3}>\s?/gm, "") // blockquote
+        .replace(/\|/g, " "); // table pipes
+}
+/** Escape text for the few places we build innerHTML (nav button label). */
+export function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, (c) => ({
+        "&": "&amp;",
+        "<": "&lt;",
+        ">": "&gt;",
+        '"': "&quot;",
+        "'": "&#39;",
+    })[c]);
+}
+/** Wrap a bare HTML fragment in a minimal document so a preview always renders
+ *  sanely; a full document is used as-is. */
+export function wrapPreviewHtml(html) {
+    const s = (html ?? "").trim();
+    if (/<!doctype|<html[\s>]/i.test(s))
+        return s;
+    return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><style>*{box-sizing:border-box}body{margin:0;padding:16px;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;color:#0f172a}</style></head><body>${s}</body></html>`;
+}
+export function addMsg(log, role, text, attachments) {
+    // Attachment chips render as their own row above the text bubble so a
+    // file-only turn (no text) still shows what the user sent.
+    if (attachments && attachments.length) {
+        const chips = el("div", `${PREFIX}-atts ${PREFIX}-${role}`);
+        for (const a of attachments) {
+            const chip = el("span", `${PREFIX}-att`);
+            chip.title = `${a.filename} (${a.contentType})`;
+            chip.textContent = `${attIcon(a.kind)} ${a.filename}`;
+            chips.appendChild(chip);
+        }
+        log.appendChild(chips);
+    }
+    const msg = el("div", `${PREFIX}-msg ${PREFIX}-${role}`);
+    msg.textContent = text;
+    if (!text && attachments && attachments.length)
+        msg.style.display = "none";
+    log.appendChild(msg);
+    return msg;
+}
+//# sourceMappingURL=dom.js.map

package/dist/dom.js.map

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

package/dist/host-actions.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Shared host protocol for Copilot — the ONE definition of the page context the
+ * assistant receives and the in-app actions it may take, reused by every
+ * surface (org, admin, marketing, onboarding). Keeping this in one place means
+ * adding a surface is a few lines, and the action allow-list can't drift between
+ * apps.
+ *
+ * SECURITY: the AI only ever NAMES an action; the host owns the name→effect
+ * mapping below. The model never receives a raw URL or endpoint.
+ */
+/** Which product surface the user is on. */
+export type AppSurface = "org" | "admin" | "marketing" | "onboarding";
+/**
+ * A structured descriptor of ONE page/route — the "page manifest". It lives next
+ * to the app's routes (one source of truth) and teaches Copilot what a page IS:
+ * its purpose, the sections on it, and the actions available there. Feeding
+ * these into the turn context turns Copilot from "knows the route name" into a
+ * page-structure-aware UI assistant.
+ */
+export interface PageManifestEntry {
+    /** Language-/account-neutral path the model uses to navigate (e.g. "/network",
+     *  or an org suffix like "/assets"). */
+    path: string;
+    /** Human title shown to the user / used by the model. */
+    title: string;
+    /** One-line "what this page is for". */
+    purpose: string;
+    /** Key sections/areas on the page (so Copilot can describe its structure). */
+    sections?: string[];
+    /** Allow-listed action name(s) that open/operate this page, when the host
+     *  prefers a named action over a raw path (e.g. org's "open-dashboards"). */
+    action?: string;
+    /** A few page-aware shortcut questions surfaced as clickable chips in the
+     *  assistant widget while the conversation is empty — the smart "where do I
+     *  start on THIS page" prompts. Clicking one sends it to Copilot. */
+    suggestions?: string[];
+}
+/** A compact navigable target the model is offered (derived from the manifest). */
+export interface NavTarget {
+    path: string;
+    title: string;
+    purpose: string;
+    /** Named action to use instead of a raw path, when set. */
+    action?: string;
+}
+/** Per-turn page context sent to the assistant (merged into the POST as
+ *  `pageContext` by `getContext`). */
+export interface PageContext {
+    app: AppSurface;
+    /** Current route/path. */
+    path: string;
+    /** Last path segment — a coarse "page" name the model can reason about. */
+    page: string;
+    /** Recent navigation breadcrumb (most-recent last, capped). */
+    recentPages: string[];
+    /** The current page's manifest descriptor (purpose + sections), when known. */
+    pageInfo?: PageManifestEntry;
+    /** The catalog of pages Copilot may open (from the manifest) — the single source
+     *  of truth for navigation, so the prompt never hardcodes a path list. */
+    navTargets?: NavTarget[];
+    /** On-page controls the Copilot may point at (highlight/scroll-to/focus-field)
+     *  — scanned from the live DOM via `scanAiTargets()`. Ids the host owns, never
+     *  selectors. Fed into the turn so the model knows what's on THIS page. */
+    uiTargets?: Array<{
+        id: string;
+        label: string;
+    }>;
+}
+/**
+ * Find the manifest entry that best describes the current path — the entry
+ * whose `path` is the longest suffix of the (normalized) current path.
+ *
+ * A segment written as `:name` matches ANY one segment, so a detail page can
+ * be declared once ("/reports/:reportId") instead of being undescribable.
+ * Without this a concrete `/reports/<uuid>` matched nothing at all — not even
+ * the list page above it, since the uuid is a further segment and the
+ * comparison was a plain suffix test — so the assistant silently lost all
+ * knowledge of which page the user was standing on.
+ *
+ * Matching is done per SEGMENT rather than by string, because a suffix test
+ * cannot tell a parameter from a literal. The longest match still wins, which
+ * keeps a specific entry ahead of a general one.
+ */
+export declare function matchManifest(path: string, manifest: PageManifestEntry[]): PageManifestEntry | undefined;
+/**
+ * Is this AI-supplied path one of the pages the manifest actually DECLARES?
+ *
+ * The manifest is the whole security surface for navigation, and until now it
+ * was only ever advice: it went into the prompt as "Pages you can open (use
+ * ONLY these to navigate)" and nothing checked the answer. The only real gate
+ * was a shape test — starts with one `/`, not `//` or `/\` — which every
+ * cross-tenant path also passes. `/accounts/<someone-else>/settings` is a
+ * root-relative in-app route by that definition, and `orgPath` returns an
+ * already-`/accounts/`-prefixed path untouched, so a model that emitted one got
+ * it loaded into the deliberately un-sandboxed, same-origin advanced frame.
+ *
+ * Matched from the START, per segment, unlike `matchManifest` — which matches a
+ * SUFFIX because it is handed a full SPA route and has to find the entry that
+ * describes it. Here the input is the account-relative path the model wrote, so
+ * the manifest's namespace has to be its PREFIX or the check is no gate at all:
+ * a suffix test admits `/accounts/<someone-else>/dashboards` on the strength of
+ * the `/dashboards` entry. Extra trailing segments ARE allowed — that is how a
+ * detail page under a declared list ("/reports/<uuid>") stays reachable — and
+ * `:param` segments match any one segment, as in the manifest itself.
+ *
+ * DECODE FIRST, THEN VALIDATE. The first cut of this refused a literal `..`
+ * segment by comparing the raw spelling, which is a blocklist — and a blocklist
+ * of shapes is exactly what produced the hole above. `%2e%2e`, `%2E%2E`, `.%2e`
+ * and `%252e%252e` all survive a literal comparison and all mean `..` by the
+ * time the URL is parsed, so `/reports/%2e%2e/%2e%2e/%2e%2e/accounts/<them>/x`
+ * walked straight through it and into the frame. `navPathSegments` resolves the
+ * path to what the browser will actually see — percent-decoded to a fixed
+ * point, NFKC-folded, backslashes and protocol-relative forms refused — and
+ * only then is each segment matched against the manifest.
+ *
+ * A dot segment is refused rather than resolved: the host prefixes the account
+ * AFTER this runs, so resolving here would judge a different path than the one
+ * the browser resolves, and no real route contains one.
+ *
+ * NO MANIFEST MEANS NO NAVIGATION. A host that declares no pages has declared
+ * nothing the model may open, and falling back to "any root-relative path" here
+ * would restore exactly the hole this closes.
+ */
+export declare function isKnownNavTarget(path: unknown, targets: readonly {
+    path?: string;
+}[] | undefined | null): path is string;
+/** Build a standard PageContext from a path (derives `page`, caps the trail).
+ *  Pass the app's page `manifest` to also attach the current page's descriptor
+ *  and the navigable-page catalog. */
+export declare function makePageContext(app: AppSurface, path: string, recentPages?: string[], manifest?: PageManifestEntry[]): PageContext;
+/**
+ * Account-relative path each named standard action opens. Single source of truth
+ * shared by `createHostActions` (which navigates the parent app there) and the
+ * widget's advanced view (which navigates the iframe there via `resolveActionPath`),
+ * so the two can't drift.
+ */
+export declare const STANDARD_ACTION_PATHS: Record<string, string>;
+/**
+ * Is this action PURE NAVIGATION — moving the user to a page and nothing else?
+ *
+ * The auto-navigate option promises exactly this and nothing more. It used to
+ * decide by asking whether the model had attached a `confirm` to its own action,
+ * which put the safety decision in the model's hands: an action it emitted
+ * without one ran instantly and unattended — and a confirm-less action can
+ * spend metered credit, so "auto-navigate" could buy things. Navigation is a
+ * closed set — enumerate it, and let everything else wait for the user to
+ * press the button.
+ */
+export declare function isNavigationAction(name: string): boolean;
+export type HostActionHandler = (data: Record<string, string>) => Promise<string | void> | string | void;
+export interface HostActionsConfig {
+    /** Account scope for the `/accounts/:id/...` standard routes (org/admin). */
+    accountId?: string;
+    /** The host's router push (in-app SPA navigation). */
+    navigate: (path: string) => void;
+    /** Point a MOUNTED asset library at a folder/asset. Supplied by the host as
+     *  `showAssetsAt` from @sgiant/assets — the router push alone cannot reach a
+     *  library that is already on screen. */
+    showAssets?: (t: {
+        folderId?: string | null;
+        assetId?: string | null;
+    }) => void;
+    /** App-specific actions, merged over the standard set (can override). */
+    handlers?: Record<string, HostActionHandler>;
+    /**
+     * The page manifest this host declares — the SAME catalogue the model is
+     * offered as "Pages you can open". A model-authored `navigate` path is
+     * checked against it (see `isKnownNavTarget`) before the router is touched,
+     * so the list stops being advice and becomes the gate. A host that passes
+     * none can navigate nowhere.
+     */
+    pages?: readonly {
+        path?: string;
+    }[];
+    /**
+     * The host's translator, for the CHIP OUTCOMES below.
+     *
+     * Every visible string the widget itself renders goes through
+     * `WIDGET_LABELS`, which is what lets a host translate the chrome. These
+     * outcomes were plain English record literals returned straight into the chip
+     * text, so a Turkish session read "Opened dashboards" and "Already there" in
+     * the middle of a Turkish conversation. Optional so a host that passes none
+     * keeps today's English.
+     */
+    t?: (key: string, defaultValue: string) => string;
+}
+/**
+ * Build the `onWidgetAction(name, data)` handler from the standard allow-listed
+ * actions + any app-specific handlers. Pass to `createAiChatWidget`.
+ */
+export declare function createHostActions(cfg: HostActionsConfig): (action: string, data: Record<string, string>) => Promise<string | void>;
+//# sourceMappingURL=host-actions.d.ts.map

package/dist/host-actions.d.ts.map

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