@guuey/chat 0.4.0 → 0.6.0

package/dist/react/components.js

@@ -98,7 +98,22 @@ export function DefaultView({ item, ctx }) {
         // never blank.
         return (_jsx("div", { className: "guuey-chat-view guuey-chat-view-negotiating guuey-chat-shimmer", children: _jsx("p", { role: "status", children: item.label ?? ctx.strings.viewNegotiating }) }));
     }
-    return (_jsxs("div", { className: "guuey-chat-view", children: [_jsx(GuueyView, { mount: mount, ...(ctx.viewProps ?? {}), onPhaseChange: (phase) => ctx.onViewPhase(item.key, phase) }), item.attribution !== null ? (_jsx("p", { className: "guuey-chat-attribution", children: item.attribution })) : null] }));
+    // The function form resolves against the ACTUAL mount (per-channel relay
+    // URLs, per-locator action scoping); it runs only when something mounts.
+    const viewProps = typeof ctx.viewProps === "function" ? ctx.viewProps(item, mount) : (ctx.viewProps ?? {});
+    return (_jsxs("div", { className: "guuey-chat-view", children: [_jsx(GuueyView, { mount: mount, ...viewProps, onPhaseChange: (phase) => ctx.onViewPhase(item.key, phase) }), item.attribution !== null ? (_jsx("p", { className: "guuey-chat-attribution", children: item.attribution })) : null] }));
+}
+/**
+ * guuey#204: the "promote and reference" chip — stands in for the one
+ * mount the host's stage shows. A real button when the host wires
+ * `onViewRef` (keyboard-accessible for free); a plain label otherwise.
+ */
+export function DefaultViewRef({ item, ctx }) {
+    if (ctx.onViewRef === undefined) {
+        return (_jsx("p", { className: "guuey-chat-view-ref", role: "note", children: item.label }));
+    }
+    const onViewRef = ctx.onViewRef;
+    return (_jsx("button", { type: "button", className: "guuey-chat-view-ref guuey-chat-view-ref-button", onClick: () => onViewRef(item), children: item.label }));
 }
 // ─── R7 ────────────────────────────────────────────────────────────────────
 /** Inline images allow https URLs and image/* base64 data — nothing else. */
@@ -160,6 +175,22 @@ export function DefaultPrompt({ item, ctx }) {
         }
         wasPending.current = item.state === "pending";
     }, [item.state]);
+    if (item.promptKind === "hitl") {
+        const s = ctx.strings;
+        // Settled records: resolved shows the CHOSEN MODE'S LABEL (ids are
+        // echo-only identity — asker-scoped semantics, spec §7); declined is
+        // the durable deny. `cancelled` is guuey's re-askable dismissal: it
+        // collapses to a record but stays answerable when expanded.
+        if (item.state === "resolved" || item.state === "declined") {
+            return (_jsx("p", { className: `guuey-chat-prompt-record guuey-chat-prompt-${item.state}`, children: item.state === "resolved"
+                    ? item.chosenModeLabel !== null
+                        ? s.promptAnsweredWith(item.chosenModeLabel)
+                        : s.promptAccept
+                    : s.promptDeclinedRecord }));
+        }
+        const answerable = item.state === "pending" || (item.state === "cancelled" && item.expanded);
+        return (_jsxs("div", { className: "guuey-chat-prompt", role: "group", children: [item.state === "cancelled" && (_jsx("button", { type: "button", className: "guuey-chat-prompt-record guuey-chat-prompt-cancelled", "aria-expanded": item.expanded, onClick: () => ctx.onToggle(item.key), children: s.promptDismissed })), answerable && (_jsxs(_Fragment, { children: [item.message !== null && _jsx("p", { className: "guuey-chat-prompt-ask", children: item.message }), _jsxs("div", { className: "guuey-chat-prompt-actions", children: [item.grantModes.length === 0 ? (_jsx("button", { ref: firstAction, type: "button", className: "guuey-chat-prompt-accept", onClick: () => ctx.onPromptAction?.(item, "accept"), children: s.promptAccept })) : (item.grantModes.map((mode, i) => (_jsx("button", { ref: i === 0 ? firstAction : undefined, type: "button", className: "guuey-chat-prompt-accept", title: mode.description, onClick: () => ctx.onPromptAction?.(item, { grantModeId: mode.id }), children: mode.label ?? mode.id }, mode.id)))), _jsx("button", { type: "button", onClick: () => ctx.onPromptAction?.(item, "decline"), children: s.promptDecline })] })] }))] }));
+    }
     if (item.state !== "pending") {
         return (_jsxs("p", { className: `guuey-chat-prompt-record guuey-chat-prompt-${item.state}`, children: [item.promptKind, ": ", item.state] }));
     }
@@ -167,6 +198,15 @@ export function DefaultPrompt({ item, ctx }) {
                     ? `${item.appId} requests ${item.requested} access`
                     : `Link your account to ${item.appId}` }), _jsxs("div", { className: "guuey-chat-prompt-actions", children: [_jsx("button", { ref: firstAction, type: "button", className: "guuey-chat-prompt-accept", onClick: () => ctx.onPromptAction?.(item, "accept"), children: "Allow" }), _jsx("button", { type: "button", onClick: () => ctx.onPromptAction?.(item, "decline"), children: "Decline" })] }), item.raw !== null ? (_jsx("pre", { className: "guuey-chat-prompt-raw", children: JSON.stringify(item.raw, null, 2) })) : null] }));
 }
+// ─── R16 ──────────────────────────────────────────────────────────────────
+/**
+ * A `role:"notice"` session annotation (spec draft.2) — a labeled,
+ * non-conversational row that must never read as agent-authored. Calm
+ * shows the quiet label; debug appends the provenance facet verbatim.
+ */
+export function DefaultNotice({ item, ctx }) {
+    return (_jsxs("div", { className: "guuey-chat-notice", role: "note", children: [_jsxs("span", { className: "guuey-chat-notice-label", children: [ctx.strings.noticeLabel, item.sourceLabel !== null ? ` · ${item.sourceLabel}` : ""] }), item.text !== "" && _jsx("span", { className: "guuey-chat-notice-text", children: item.text })] }));
+}
 // ─── R11 ───────────────────────────────────────────────────────────────────
 export function DefaultError({ item, ctx }) {
     return (_jsxs("div", { className: `guuey-chat-error guuey-chat-error-${item.family}`, role: "alert", children: [_jsx("p", { children: item.copy }), ctx.onErrorAction !== undefined && (item.family === "transient" || item.family === "auth") ? (_jsx("button", { type: "button", className: "guuey-chat-error-action", onClick: () => ctx.onErrorAction?.(item), children: item.family === "auth" ? ctx.strings.errorAuth : ctx.strings.userRetry })) : null, item.verbatim !== null ? _jsx("pre", { className: "guuey-chat-error-verbatim", children: item.verbatim }) : null] }));
@@ -193,10 +233,12 @@ export const defaultTranscriptComponents = {
     toolGroup: DefaultToolGroup,
     dataResult: DefaultDataResult,
     view: DefaultView,
+    viewRef: DefaultViewRef,
     media: DefaultMedia,
     code: DefaultCode,
     citations: DefaultCitations,
     prompt: DefaultPrompt,
+    notice: DefaultNotice,
     error: DefaultError,
     history: DefaultHistoryBoundary,
     compaction: DefaultCompaction,
@@ -234,6 +276,10 @@ export function renderItem(item, components, ctx) {
             const C = components.view;
             return _jsx(C, { item: item, ctx: ctx }, item.key);
         }
+        case "viewRef": {
+            const C = components.viewRef;
+            return _jsx(C, { item: item, ctx: ctx }, item.key);
+        }
         case "media": {
             const C = components.media;
             return _jsx(C, { item: item, ctx: ctx }, item.key);
@@ -250,6 +296,10 @@ export function renderItem(item, components, ctx) {
             const C = components.prompt;
             return _jsx(C, { item: item, ctx: ctx }, item.key);
         }
+        case "notice": {
+            const C = components.notice;
+            return _jsx(C, { item: item, ctx: ctx }, item.key);
+        }
         case "error": {
             const C = components.error;
             return _jsx(C, { item: item, ctx: ctx }, item.key);

package/dist/react/guuey-chat.d.ts

@@ -31,17 +31,59 @@
  * adapter (e.g. `createWebAdapters({ apiBaseUrl, … })`) and a persisted
  * threadId rehydrates on mount — text transcript + persisted cards, which
  * mount through the same R6 path as live views. Nothing here to configure.
+ *
+ * ## The imperative seam (guuey#210)
+ *
+ * Suggested-prompt chips and other host-driven sends stay on the
+ * batteries-included path via {@link GuueyChatHandle} — a ref handle
+ * (`forwardRef`) and/or the `onReady` callback, ONE stable object for the
+ * component's whole life. `send` runs through exactly the Send button's
+ * gate (never bypasses it; the typed draft is left untouched — a chip send
+ * must not eat a half-typed message); `prefill` mirrors the widget's
+ * staged-composer semantics (append joins with a space, never clobbers).
+ * Web-only for now: the native tier ships `<NativeTranscript>` without a
+ * native GuueyChat, so there is no native surface to put a handle on yet.
  */
-import { type CSSProperties, type ReactNode } from "react";
+import { type CSSProperties } from "react";
 import { type AgentInvokeAdapters } from "@guuey/agent-client";
+import type { AgHitlAnswer, AgPausedAsk } from "@silverprotocol/core";
 import type { UiResourceReader } from "@guuey/mcp-apps-host";
 import { type TranscriptPolicy } from "../policy.js";
 import { type ChatStrings } from "../strings.js";
 import { type GuueyChatTheme } from "../theme.js";
-import type { ErrorItem, PromptItem } from "../types.js";
+import type { ChatDebugEvent, ErrorItem, PromptItem } from "../types.js";
 import type { ThemeMode } from "./theme-css.js";
 import { type TranscriptWindowing } from "./transcript.js";
 import type { TranscriptComponents, TranscriptItemContext } from "./components.js";
+/**
+ * The imperative seam (guuey#210): programmatic send/prefill/focus for
+ * hosts that stay on the batteries-included path (suggested-prompt chips
+ * being the filing use case). Reach it via `ref` or `onReady` — both
+ * deliver the SAME stable object, valid for the component's whole life.
+ */
+export interface GuueyChatHandle {
+    /**
+     * Send `text` through exactly the Send button's gate: returns `false`
+     * and does nothing when chat is unavailable (`endpointUrl === null`), a
+     * turn is in flight, or the text is blank — it NEVER bypasses the
+     * composer's rules. The typed draft is left untouched (a programmatic
+     * send must not eat a half-typed message). Failures surface the same
+     * way a composer send's do (the hook's `error` / R0 failed-send).
+     */
+    send(text: string): boolean;
+    /**
+     * Put `text` into the composer draft. `append: true` joins onto a
+     * non-empty draft with a single space (the widget's staged-composer
+     * semantic — never clobbers); default replaces. Focuses the input
+     * unless `focus: false`.
+     */
+    prefill(text: string, opts?: {
+        focus?: boolean;
+        append?: boolean;
+    }): void;
+    /** Focus the composer input. */
+    focusComposer(): void;
+}
 export interface GuueyChatProps {
     /** Pod base URL (with or without `/agent/invoke`). `null` disables chat. */
     endpointUrl: string | null;
@@ -67,6 +109,8 @@ export interface GuueyChatProps {
     window?: TranscriptWindowing | false;
     /** R6 locator resolution (history cards). See `useTranscript`. */
     reader?: UiResourceReader;
+    /** The debug sink (spec §5) — fires only under the debug policy. */
+    onDebugEvent?: (event: ChatDebugEvent) => void;
     /** R6 pass-through (relay hook, sandbox page/flags, host context…). */
     viewProps?: TranscriptItemContext["viewProps"];
     /**
@@ -74,11 +118,25 @@ export interface GuueyChatProps {
      * The transcript record moves regardless; without a handler the prompt
      * card is record-only.
      */
-    onPromptAction?: (item: PromptItem, action: "accept" | "decline" | "dismiss") => void;
+    onPromptAction?: (item: PromptItem, action: "accept" | "decline" | "dismiss" | {
+        grantModeId: string;
+    }) => void;
+    /**
+     * Receives the VALIDATED wire answer for an AgJSON HITL ask (spec
+     * draft.2) — the host owns delivering it (the kit has no answer
+     * transport). Fired after the transcript record moves.
+     */
+    onHitlAnswer?: (answer: AgHitlAnswer, ask: AgPausedAsk) => void;
     /** R11 action slot (sign-in / retry affordances). */
     onErrorAction?: (item: ErrorItem) => void;
+    /**
+     * Callback route to the {@link GuueyChatHandle} for hosts that prefer
+     * wiring over refs. Fires ONCE per component instance, on mount, with
+     * the same stable handle the ref receives.
+     */
+    onReady?: (handle: GuueyChatHandle) => void;
     className?: string;
     style?: CSSProperties;
 }
-export declare function GuueyChat(props: GuueyChatProps): ReactNode;
+export declare const GuueyChat: import("react").ForwardRefExoticComponent<GuueyChatProps & import("react").RefAttributes<GuueyChatHandle>>;
 //# sourceMappingURL=guuey-chat.d.ts.map

package/dist/react/guuey-chat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guuey-chat.d.ts","sourceRoot":"","sources":["../../src/react/guuey-chat.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EAAkC,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAC3F,OAAO,EAAqB,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAElF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAA2B,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAmB,MAAM,aAAa,CAAC;AAC1E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAc,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAGnF,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,uEAAuE;IACvE,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACnC,gEAAgE;IAChE,UAAU,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC3C,wEAAwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/B,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,wDAAwD;IACxD,MAAM,CAAC,EAAE,mBAAmB,GAAG,KAAK,CAAC;IACrC,kEAAkE;IAClE,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,uEAAuE;IACvE,SAAS,CAAC,EAAE,qBAAqB,CAAC,WAAW,CAAC,CAAC;IAC/C;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,KAAK,IAAI,CAAC;IACtF,qDAAqD;IACrD,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAQD,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,CAsI1D"}
+{"version":3,"file":"guuey-chat.d.ts","sourceRoot":"","sources":["../../src/react/guuey-chat.tsx"],"names":[],"mappings":"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"}

package/dist/react/guuey-chat.js

@@ -32,8 +32,20 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * adapter (e.g. `createWebAdapters({ apiBaseUrl, … })`) and a persisted
  * threadId rehydrates on mount — text transcript + persisted cards, which
  * mount through the same R6 path as live views. Nothing here to configure.
+ *
+ * ## The imperative seam (guuey#210)
+ *
+ * Suggested-prompt chips and other host-driven sends stay on the
+ * batteries-included path via {@link GuueyChatHandle} — a ref handle
+ * (`forwardRef`) and/or the `onReady` callback, ONE stable object for the
+ * component's whole life. `send` runs through exactly the Send button's
+ * gate (never bypasses it; the typed draft is left untouched — a chip send
+ * must not eat a half-typed message); `prefill` mirrors the widget's
+ * staged-composer semantics (append joins with a space, never clobbers).
+ * Web-only for now: the native tier ships `<NativeTranscript>` without a
+ * native GuueyChat, so there is no native surface to put a handle on yet.
  */
-import { useCallback, useMemo, useState } from "react";
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState, } from "react";
 import { createWebAdapters } from "@guuey/agent-client";
 import { useAgentInvoke } from "@guuey/agent-client/react";
 import { calmPolicy, debugPolicy } from "../policy.js";
@@ -46,8 +58,8 @@ const PROMPT_STATE = {
     decline: "declined",
     dismiss: "dismissed",
 };
-export function GuueyChat(props) {
-    const { endpointUrl, appId, adapters: adaptersProp, preset = "calm", policy: policyOverrides, components, strings: stringOverrides, theme = DEFAULT_CHAT_THEME, mode = "light", window: windowing, reader, viewProps, onPromptAction, onErrorAction, className, style, } = props;
+export const GuueyChat = forwardRef(function GuueyChat(props, ref) {
+    const { endpointUrl, appId, adapters: adaptersProp, preset = "calm", policy: policyOverrides, components, strings: stringOverrides, theme = DEFAULT_CHAT_THEME, mode = "light", window: windowing, reader, onDebugEvent, viewProps, onPromptAction, onHitlAnswer, onErrorAction, onReady, className, style, } = props;
     const adapters = useMemo(() => adaptersProp ?? createWebAdapters(), [adaptersProp]);
     const invoke = useAgentInvoke({ endpointUrl, ...(appId !== undefined ? { appId } : {}), adapters, preserveBlocks: true });
     const policy = useMemo(() => {
@@ -59,17 +71,61 @@ export function GuueyChat(props) {
         };
         return factory({ ...policyOverrides, strings });
     }, [preset, policyOverrides, stringOverrides]);
-    const { inputs, resolvePrompt } = useTranscriptInputs(invoke);
+    const { inputs, resolvePrompt, answerHitlPrompt } = useTranscriptInputs(invoke);
     const { plan, toggle, resolvedMounts, onViewPhase } = useTranscript({
         inputs,
         policy,
         ...(reader !== undefined ? { reader } : {}),
+        ...(onDebugEvent !== undefined ? { onDebugEvent } : {}),
     });
     // ── Composer ─────────────────────────────────────────────────────────
     const [input, setInput] = useState("");
+    const inputRef = useRef(null);
     const busy = invoke.status !== "ready";
     const available = endpointUrl !== null;
     const canSend = available && !busy && input.trim() !== "";
+    // ── The imperative seam (guuey#210) ──────────────────────────────────
+    // ONE stable handle for the component's whole life (hosts capture it in
+    // `onReady` and keep it), reading live truth through a ref so a call
+    // always sees the CURRENT gate — never a stale closure's.
+    const liveRef = useRef({ available, busy, invoke, onReady });
+    useEffect(() => {
+        liveRef.current = { available, busy, invoke, onReady };
+    });
+    const handle = useMemo(() => ({
+        send: (text) => {
+            const live = liveRef.current;
+            const trimmed = text.trim();
+            // Exactly the Send button's gate — a handle send never bypasses it.
+            if (!live.available || live.busy || trimmed === "")
+                return false;
+            void live.invoke.send(trimmed).catch(() => {
+                // Same contract as submit: the hook owns failure surfacing.
+            });
+            return true;
+        },
+        prefill: (text, opts) => {
+            setInput((prev) => 
+            // The widget's staged-composer semantic: append joins with a
+            // space onto a non-empty draft, never clobbers it.
+            opts?.append === true && prev.trim() !== "" ? `${prev.trimEnd()} ${text}` : text);
+            if (opts?.focus !== false)
+                inputRef.current?.focus();
+        },
+        focusComposer: () => {
+            inputRef.current?.focus();
+        },
+    }), []);
+    useImperativeHandle(ref, () => handle, [handle]);
+    // `onReady` fires once per instance, on mount, with the stable handle
+    // (guarded ref: StrictMode's remount cycle must not double-fire it).
+    const readyFiredRef = useRef(false);
+    useEffect(() => {
+        if (readyFiredRef.current)
+            return;
+        readyFiredRef.current = true;
+        liveRef.current.onReady?.(handle);
+    }, [handle]);
     const submit = useCallback(() => {
         const text = input.trim();
         if (text === "" || !available || busy)
@@ -85,14 +141,23 @@ export function GuueyChat(props) {
         });
     }, [invoke]);
     const handlePromptAction = useCallback((item, action) => {
-        resolvePrompt(item.promptId, PROMPT_STATE[action]);
+        if (item.promptKind === "hitl") {
+            const answer = answerHitlPrompt(item.ask, typeof action === "object" ? action : action === "accept" ? "accept" : action);
+            onHitlAnswer?.(answer, item.ask);
+            onPromptAction?.(item, action);
+            return;
+        }
+        // Profile prompts only ever receive the string actions (the default
+        // card renders no mode buttons for them).
+        if (typeof action !== "object")
+            resolvePrompt(item.promptId, PROMPT_STATE[action]);
         onPromptAction?.(item, action);
-    }, [resolvePrompt, onPromptAction]);
+    }, [resolvePrompt, answerHitlPrompt, onHitlAnswer, onPromptAction]);
     const strings = policy.strings;
     return (_jsxs("div", { className: `guuey-chat-surface${className !== undefined ? ` ${className}` : ""}`, style: style, children: [_jsx(Transcript, { plan: plan, strings: strings, theme: theme, mode: mode, ...(windowing !== undefined ? { window: windowing } : {}), ...(components !== undefined ? { components } : {}), onToggle: toggle, onRetry: handleRetry, onPromptAction: handlePromptAction, ...(onErrorAction !== undefined ? { onErrorAction } : {}), resolvedMounts: resolvedMounts, onViewPhase: onViewPhase, ...(viewProps !== undefined ? { viewProps } : {}) }), _jsxs("form", { className: "guuey-chat-composer", onSubmit: (e) => {
                     e.preventDefault();
                     submit();
-                }, children: [_jsx("textarea", { className: "guuey-chat-composer-input", rows: 1, value: input, onChange: (e) => setInput(e.target.value), onKeyDown: (e) => {
+                }, children: [_jsx("textarea", { ref: inputRef, className: "guuey-chat-composer-input", rows: 1, value: input, onChange: (e) => setInput(e.target.value), onKeyDown: (e) => {
                             // `isComposing` guards IME input: an Enter that commits a
                             // candidate must not also send the message.
                             if (e.key === "Enter" && !e.shiftKey && !e.nativeEvent.isComposing) {
@@ -100,4 +165,4 @@ export function GuueyChat(props) {
                                 submit();
                             }
                         }, disabled: !available, "aria-label": strings.composerLabel, placeholder: available ? strings.composerPlaceholder : strings.composerUnavailable }), busy ? (_jsx("button", { type: "button", className: "guuey-chat-composer-stop", onClick: () => invoke.abort(), children: strings.stop })) : (_jsx("button", { type: "submit", className: "guuey-chat-composer-send", disabled: !canSend, children: strings.send }))] })] }));
-}
+});

package/dist/react/transcript.d.ts

@@ -25,7 +25,7 @@ export interface TranscriptWindowing {
     /** Trailing items rendered; earlier ones sit behind the expander. */
     tail: number;
 }
-export interface TranscriptProps extends Pick<TranscriptItemContext, "onToggle" | "onRetry" | "onPromptAction" | "onErrorAction" | "resolvedMounts" | "onViewPhase" | "viewProps"> {
+export interface TranscriptProps extends Pick<TranscriptItemContext, "onToggle" | "onRetry" | "onPromptAction" | "onErrorAction" | "resolvedMounts" | "onViewPhase" | "onViewRef" | "viewProps"> {
     plan: TranscriptPlan;
     /** Per-slot component overrides (spec §3's override column). */
     components?: Partial<TranscriptComponents>;

package/dist/react/transcript.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../../src/react/transcript.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAML,KAAK,aAAa,EAClB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAGL,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC3B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAK9D,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eACf,SAAQ,IAAI,CACV,qBAAqB,EACrB,UAAU,GAAG,SAAS,GAAG,gBAAgB,GAAG,eAAe,GAAG,gBAAgB,GAAG,aAAa,GAAG,WAAW,CAC7G;IACD,IAAI,EAAE,cAAc,CAAC;IACrB,gEAAgE;IAChE,UAAU,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC3C,gEAAgE;IAChE,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,yEAAyE;IACzE,MAAM,CAAC,EAAE,mBAAmB,GAAG,KAAK,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,CA2H5D"}
+{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../../src/react/transcript.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAML,KAAK,aAAa,EAClB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAGL,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC3B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAK9D,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eACf,SAAQ,IAAI,CACV,qBAAqB,EACrB,UAAU,GAAG,SAAS,GAAG,gBAAgB,GAAG,eAAe,GAAG,gBAAgB,GAAG,aAAa,GAAG,WAAW,GAAG,WAAW,CAC3H;IACD,IAAI,EAAE,cAAc,CAAC;IACrB,gEAAgE;IAChE,UAAU,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC3C,gEAAgE;IAChE,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,yEAAyE;IACzE,MAAM,CAAC,EAAE,mBAAmB,GAAG,KAAK,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,CA4H5D"}

package/dist/react/transcript.js

@@ -24,9 +24,9 @@ import { themeCssVars } from "./theme-css.js";
 /** How close to the bottom (px) still counts as pinned. */
 const PIN_THRESHOLD_PX = 48;
 export function Transcript(props) {
-    const { plan, components, strings = defaultChatStrings, theme = DEFAULT_CHAT_THEME, mode = "light", window: windowing = { tail: 80 }, className, style, onToggle, onRetry, onPromptAction, onErrorAction, resolvedMounts, onViewPhase, viewProps, } = props;
+    const { plan, components, strings = defaultChatStrings, theme = DEFAULT_CHAT_THEME, mode = "light", window: windowing = { tail: 80 }, className, style, onToggle, onRetry, onPromptAction, onErrorAction, resolvedMounts, onViewPhase, onViewRef, viewProps, } = props;
     const resolvedComponents = useMemo(() => ({ ...defaultTranscriptComponents, ...components }), [components]);
-    const ctx = useMemo(() => ({ strings, onToggle, onRetry, onPromptAction, onErrorAction, resolvedMounts, onViewPhase, viewProps }), [strings, onToggle, onRetry, onPromptAction, onErrorAction, resolvedMounts, onViewPhase, viewProps]);
+    const ctx = useMemo(() => ({ strings, onToggle, onRetry, onPromptAction, onErrorAction, resolvedMounts, onViewPhase, onViewRef, viewProps }), [strings, onToggle, onRetry, onPromptAction, onErrorAction, resolvedMounts, onViewPhase, onViewRef, viewProps]);
     // ── Windowing ────────────────────────────────────────────────────────
     const [extraShown, setExtraShown] = useState(0);
     const tail = windowing === false ? Number.POSITIVE_INFINITY : windowing.tail;

package/dist/react/use-transcript.d.ts

@@ -1,7 +1,9 @@
 import type { UseAgentInvokeReturn } from "@guuey/agent-client";
+import type { AgHitlAnswer, AgPausedAsk } from "@silverprotocol/core";
 import { type ResolvedViewMount, type UiResourceReader, type ViewHostPhase } from "@guuey/mcp-apps-host";
+import { type HitlPromptAction } from "../hitl.js";
 import type { TranscriptPolicy } from "../policy.js";
-import type { ItemKey, TranscriptInputs, TranscriptOverrides, TranscriptPlan } from "../types.js";
+import type { ChatDebugEvent, ItemKey, TranscriptInputs, TranscriptOverrides, TranscriptPlan } from "../types.js";
 export interface UseTranscriptArgs {
     inputs: TranscriptInputs;
     policy: TranscriptPolicy;
@@ -12,6 +14,13 @@ export interface UseTranscriptArgs {
      * resolution — labeled, never blank.
      */
     reader?: UiResourceReader;
+    /**
+     * The debug sink (spec §5, real API since the #135 refinement wave):
+     * receives {@link ChatDebugEvent}s — view-phase transitions, R15
+     * unknown-block sightings, the #192 recovered-turn marker. Fires ONLY
+     * under the debug policy (`debugDetail`); `calm` ignores it by design.
+     */
+    onDebugEvent?: (event: ChatDebugEvent) => void;
 }
 export interface UseTranscriptResult {
     plan: TranscriptPlan;
@@ -24,7 +33,7 @@ export interface UseTranscriptResult {
     /** Locator resolutions: mount material, or `"expired"` for a miss. */
     resolvedMounts: ReadonlyMap<ItemKey, ResolvedViewMount | "expired">;
 }
-export declare function useTranscript({ inputs, policy, reader }: UseTranscriptArgs): UseTranscriptResult;
+export declare function useTranscript({ inputs, policy, reader, onDebugEvent, }: UseTranscriptArgs): UseTranscriptResult;
 export interface UseTranscriptInputsResult {
     inputs: TranscriptInputs;
     /**
@@ -34,6 +43,16 @@ export interface UseTranscriptInputsResult {
      * without a recorded action reads as `dismissed`.
      */
     resolvePrompt: (id: string, state: "answered" | "declined" | "dismissed") => void;
+    /**
+     * Answer an AgJSON HITL ask (spec draft.2): constructs the wire answer,
+     * VALIDATES it against the ask's persisted record (`validateHitlAnswer`
+     * — required-iff-declared, echo-must-be-declared, requestState byte-echo)
+     * BEFORE anything dispatches, records it in the ledger, and returns it
+     * for the HOST to deliver — the kit renders and validates; the answer
+     * transport is the host's (no client→pod hitl-answer channel exists on
+     * the guuey wire today; see the #16 producer flag).
+     */
+    answerHitlPrompt: (ask: AgPausedAsk, action: HitlPromptAction) => AgHitlAnswer;
 }
 export declare function useTranscriptInputs(invoke: UseAgentInvokeReturn): UseTranscriptInputsResult;
 //# sourceMappingURL=use-transcript.d.ts.map

package/dist/react/use-transcript.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-transcript.d.ts","sourceRoot":"","sources":["../../src/react/use-transcript.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EACV,OAAO,EAEP,gBAAgB,EAEhB,mBAAmB,EACnB,cAAc,EACf,MAAM,aAAa,CAAC;AAIrB,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,EAAE,gBAAgB,CAAC;IACzB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,cAAc,CAAC;IACrB,wEAAwE;IACxE,MAAM,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/B,mEAAmE;IACnE,SAAS,EAAE,mBAAmB,CAAC;IAC/B,0EAA0E;IAC1E,WAAW,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAC1D,sEAAsE;IACtE,cAAc,EAAE,WAAW,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,CAAC,CAAC;CACrE;AAED,wBAAgB,aAAa,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,iBAAiB,GAAG,mBAAmB,CAwEhG;AAID,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,gBAAgB,CAAC;IACzB;;;;;OAKG;IACH,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,UAAU,GAAG,WAAW,KAAK,IAAI,CAAC;CACnF;AAKD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,GAAG,yBAAyB,CA6H3F"}
+{"version":3,"file":"use-transcript.d.ts","sourceRoot":"","sources":["../../src/react/use-transcript.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAA+D,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEhH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EACV,cAAc,EACd,OAAO,EAEP,gBAAgB,EAEhB,mBAAmB,EACnB,cAAc,EACf,MAAM,aAAa,CAAC;AAIrB,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,EAAE,gBAAgB,CAAC;IACzB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;CAChD;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,cAAc,CAAC;IACrB,wEAAwE;IACxE,MAAM,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/B,mEAAmE;IACnE,SAAS,EAAE,mBAAmB,CAAC;IAC/B,0EAA0E;IAC1E,WAAW,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IAC1D,sEAAsE;IACtE,cAAc,EAAE,WAAW,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,CAAC,CAAC;CACrE;AAED,wBAAgB,aAAa,CAAC,EAC5B,MAAM,EACN,MAAM,EACN,MAAM,EACN,YAAY,GACb,EAAE,iBAAiB,GAAG,mBAAmB,CA2GzC;AAID,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,gBAAgB,CAAC;IACzB;;;;;OAKG;IACH,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,UAAU,GAAG,WAAW,KAAK,IAAI,CAAC;IAClF;;;;;;;;OAQG;IACH,gBAAgB,EAAE,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,gBAAgB,KAAK,YAAY,CAAC;CAChF;AAKD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,GAAG,yBAAyB,CA+I3F"}

package/dist/react/use-transcript.js

@@ -13,11 +13,15 @@
  */
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { resolveViewMount, } from "@guuey/mcp-apps-host";
+import { buildHitlAnswer, hitlPromptsFromFold } from "../hitl.js";
 import { planTranscript } from "../plan.js";
-export function useTranscript({ inputs, policy, reader }) {
+export function useTranscript({ inputs, policy, reader, onDebugEvent, }) {
     const [overrides, setOverrides] = useState({});
     const [phases, setPhases] = useState({});
     const [resolvedMounts, setResolvedMounts] = useState(new Map());
+    // The debug sink (gated on the debug policy — calm ignores it, spec §5).
+    const debugSink = useRef(null);
+    debugSink.current = policy.debugDetail && onDebugEvent !== undefined ? onDebugEvent : null;
     const merged = useMemo(() => ({ ...inputs, viewPhases: { ...inputs.viewPhases, ...phases } }), [inputs, phases]);
     const plan = useMemo(() => planTranscript(merged, policy, overrides), [merged, policy, overrides]);
     // Toggle flips the item's CURRENT resolved state (policy default or a
@@ -46,9 +50,38 @@ export function useTranscript({ inputs, policy, reader }) {
         const current = findExpanded();
         setOverrides((prev) => ({ ...prev, [key]: { expanded: !current } }));
     }, []);
+    // Mirror of `phases` for the change check OUTSIDE the state updater — a
+    // sink call inside an updater would double-fire under StrictMode.
+    const phasesRef = useRef({});
     const onViewPhase = useCallback((key, phase) => {
+        if (phasesRef.current[key] !== phase) {
+            phasesRef.current = { ...phasesRef.current, [key]: phase };
+            debugSink.current?.({ type: "view-phase", key, phase });
+        }
         setPhases((prev) => (prev[key] === phase ? prev : { ...prev, [key]: phase }));
     }, []);
+    // Plan-derived debug events, emitted once per sighting (post-render — the
+    // plan itself stays pure data).
+    const emittedUnknowns = useRef(new Set());
+    const recoveryEmitted = useRef(false);
+    useEffect(() => {
+        const sink = debugSink.current;
+        if (sink === null)
+            return;
+        for (const item of plan.items) {
+            if (item.kind !== "unknown" || emittedUnknowns.current.has(item.key))
+                continue;
+            emittedUnknowns.current.add(item.key);
+            sink({ type: "unknown-block", key: item.key, typeName: item.typeName, byteSize: item.byteSize });
+        }
+        if (plan.recovery !== null && !recoveryEmitted.current) {
+            recoveryEmitted.current = true;
+            sink({ type: "turn-recovered", marker: plan.recovery });
+        }
+        else if (plan.recovery === null) {
+            recoveryEmitted.current = false;
+        }
+    }, [plan]);
     // Locator resolution — one read per locator key, misses become "expired".
     const readerRef = useRef(reader);
     readerRef.current = reader;
@@ -66,6 +99,10 @@ export function useTranscript({ inputs, policy, reader }) {
             inFlight.current.add(item.key);
             const settle = (value) => {
                 inFlight.current.delete(item.key);
+                // The R13 expired verdict is a phase transition too (debug sink).
+                if (value === "expired") {
+                    debugSink.current?.({ type: "view-phase", key: item.key, phase: "expired" });
+                }
                 setResolvedMounts((prev) => {
                     const next = new Map(prev);
                     next.set(item.key, value);
@@ -156,6 +193,22 @@ export function useTranscriptInputs(invoke) {
         if (pending?.kind === "link")
             invoke.clearProfileLinkRequest();
     }, [invoke, prompts]);
+    // HITL ledger (spec draft.2): asks come from the FOLD's persisted
+    // records; this ledger holds only the host-side answers, keyed by askId.
+    // A `cancelled` record keeps the card re-askable (guuey's #16 ruling) —
+    // a later action on the same ask simply overwrites it.
+    const [hitlAnswers, setHitlAnswers] = useState({});
+    const answerHitlPrompt = useCallback((ask, action) => {
+        const answer = buildHitlAnswer(ask, action);
+        setHitlAnswers((prev) => ({
+            ...prev,
+            [ask.askId]: {
+                status: answer.status,
+                ...(answer.grantModeId !== undefined ? { grantModeId: answer.grantModeId } : {}),
+            },
+        }));
+        return answer;
+    }, []);
     const inputs = useMemo(() => {
         // Source-ownership split (plan.ts's rules): the trailing assistant
         // entry is the IN-FLIGHT fold (or the abort-kept partial) — it moves to
@@ -176,7 +229,7 @@ export function useTranscriptInputs(invoke) {
             statusElapsedMs: elapsedMs,
             activeTool: invoke.activeTool,
             error: invoke.error !== null ? { message: invoke.error, code: invoke.errorCode } : null,
-            prompts,
+            prompts: [...prompts, ...hitlPromptsFromFold(invoke.reduceResult, hitlAnswers)],
             messages,
             ...(invoke.historyCards.length > 0 ? { historyCards: invoke.historyCards } : {}),
             sendStates: invoke.sendStates,
@@ -196,6 +249,7 @@ export function useTranscriptInputs(invoke) {
         invoke.adopted,
         elapsedMs,
         prompts,
+        hitlAnswers,
     ]);
-    return { inputs, resolvePrompt };
+    return { inputs, resolvePrompt, answerHitlPrompt };
 }

package/dist/react.d.ts

@@ -13,9 +13,9 @@
  * → drop to `planTranscript` + `attachViewHost` and render it all yourself.
  */
 export { Transcript, type TranscriptProps, type TranscriptWindowing, } from "./react/transcript.js";
-export { defaultTranscriptComponents, renderItem, DefaultUserMessage, DefaultText, DefaultReasoning, DefaultTool, DefaultToolGroup, DefaultDataResult, DefaultView, DefaultMedia, DefaultCode, DefaultCitations, DefaultPrompt, DefaultError, DefaultHistoryBoundary, DefaultCompaction, DefaultUnknown, DefaultStatus, type TranscriptComponents, type TranscriptItemContext, } from "./react/components.js";
+export { defaultTranscriptComponents, renderItem, DefaultUserMessage, DefaultText, DefaultReasoning, DefaultTool, DefaultToolGroup, DefaultDataResult, DefaultView, DefaultViewRef, DefaultMedia, DefaultCode, DefaultCitations, DefaultPrompt, DefaultError, DefaultHistoryBoundary, DefaultCompaction, DefaultUnknown, DefaultStatus, type TranscriptComponents, type TranscriptItemContext, type ViewSlotProps, } from "./react/components.js";
 export { useTranscript, useTranscriptInputs, type UseTranscriptArgs, type UseTranscriptResult, type UseTranscriptInputsResult, } from "./react/use-transcript.js";
-export { GuueyChat, type GuueyChatProps } from "./react/guuey-chat.js";
+export { GuueyChat, type GuueyChatProps, type GuueyChatHandle } from "./react/guuey-chat.js";
 export { Markdown } from "./react/markdown.js";
 export { themeCssVars, type ThemeMode } from "./react/theme-css.js";
 //# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EACL,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,mBAAmB,GACzB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,2BAA2B,EAC3B,UAAU,EACV,kBAAkB,EAClB,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,sBAAsB,EACtB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,GAC/B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EACL,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,mBAAmB,GACzB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,2BAA2B,EAC3B,UAAU,EACV,kBAAkB,EAClB,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,sBAAsB,EACtB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,GACnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,GAC/B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7F,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/react.js

@@ -13,7 +13,7 @@
  * → drop to `planTranscript` + `attachViewHost` and render it all yourself.
  */
 export { Transcript, } from "./react/transcript.js";
-export { defaultTranscriptComponents, renderItem, DefaultUserMessage, DefaultText, DefaultReasoning, DefaultTool, DefaultToolGroup, DefaultDataResult, DefaultView, DefaultMedia, DefaultCode, DefaultCitations, DefaultPrompt, DefaultError, DefaultHistoryBoundary, DefaultCompaction, DefaultUnknown, DefaultStatus, } from "./react/components.js";
+export { defaultTranscriptComponents, renderItem, DefaultUserMessage, DefaultText, DefaultReasoning, DefaultTool, DefaultToolGroup, DefaultDataResult, DefaultView, DefaultViewRef, DefaultMedia, DefaultCode, DefaultCitations, DefaultPrompt, DefaultError, DefaultHistoryBoundary, DefaultCompaction, DefaultUnknown, DefaultStatus, } from "./react/components.js";
 export { useTranscript, useTranscriptInputs, } from "./react/use-transcript.js";
 export { GuueyChat } from "./react/guuey-chat.js";
 export { Markdown } from "./react/markdown.js";

package/dist/strings.d.ts

@@ -47,6 +47,10 @@ export interface ChatStrings {
     viewInlineFallback: string;
     viewExpired: string;
     viewSandboxUnavailable: string;
+    /** guuey#204: the chip text for a mount promoted to a host stage/canvas. */
+    viewPromoted: (title: string) => string;
+    /** Chip title when the mount has no producing-call title (history cards). */
+    viewRefFallbackTitle: string;
     /** #192 debug-preset marker (calm never shows it — spec §3, F10). */
     recoveredFromHistory: string;
     /** R5 empty result. */
@@ -61,6 +65,15 @@ export interface ChatStrings {
     showEarlier: (count: number) => string;
     copy: string;
     copied: string;
+    /** R10 hitl actions (spec draft.2) — mode buttons use the ASKER's labels. */
+    promptAccept: string;
+    promptDecline: string;
+    promptDismissed: string;
+    /** The answered record line, e.g. `Allowed — Always`. */
+    promptAnsweredWith: (modeLabel: string) => string;
+    promptDeclinedRecord: string;
+    /** R16 — the notice row's label (provenance shows only under debug). */
+    noticeLabel: string;
     /** The 3c composer (`<GuueyChat>`). */
     composerPlaceholder: string;
     composerUnavailable: string;

package/dist/strings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strings.d.ts","sourceRoot":"","sources":["../src/strings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IACzC,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAEhB,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IAErB,aAAa;IACb,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACrC,iBAAiB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAC7C,eAAe,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IAEvC,UAAU;IACV,cAAc,EAAE,MAAM,CAAC;IAEvB,UAAU;IACV,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAErC,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;IAErB,WAAW;IACX,UAAU,EAAE,MAAM,CAAC;IAEnB,UAAU;IACV,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAElB,iBAAiB;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB,EAAE,MAAM,CAAC;IAE/B,qEAAqE;IACrE,oBAAoB,EAAE,MAAM,CAAC;IAE7B,uBAAuB;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IAErC,kBAAkB;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IAEnB,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IAEf,uCAAuC;IACvC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,eAAO,MAAM,kBAAkB,EAAE,WAsDhC,CAAC"}
+{"version":3,"file":"strings.d.ts","sourceRoot":"","sources":["../src/strings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IACzC,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAEhB,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IAErB,aAAa;IACb,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACrC,iBAAiB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAC7C,eAAe,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IAEvC,UAAU;IACV,cAAc,EAAE,MAAM,CAAC;IAEvB,UAAU;IACV,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAErC,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;IAErB,WAAW;IACX,UAAU,EAAE,MAAM,CAAC;IAEnB,UAAU;IACV,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAElB,iBAAiB;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,4EAA4E;IAC5E,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACxC,6EAA6E;IAC7E,oBAAoB,EAAE,MAAM,CAAC;IAE7B,qEAAqE;IACrE,oBAAoB,EAAE,MAAM,CAAC;IAE7B,uBAAuB;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IAErC,kBAAkB;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IAEnB,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IAEf,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,kBAAkB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IAClD,oBAAoB,EAAE,MAAM,CAAC;IAE7B,wEAAwE;IACxE,WAAW,EAAE,MAAM,CAAC;IAEpB,uCAAuC;IACvC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,eAAO,MAAM,kBAAkB,EAAE,WAgEhC,CAAC"}