@guuey/chat 0.4.0

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

@@ -0,0 +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"}

package/dist/react/guuey-chat.js

@@ -0,0 +1,103 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * `<GuueyChat>` — the batteries-included surface (guuey#135 wave 3c): the
+ * whole tier stack wired end to end, PLUS the composer (which arrives here
+ * per the founder ruling — earlier tiers are transcript-only).
+ *
+ *     useAgentInvoke → useTranscriptInputs → useTranscript → <Transcript>
+ *                                                          + the composer
+ *
+ * It is a THIN composition of the exported tiers — every wire below is a
+ * public API, so a builder ejects one level down (own composer around
+ * `<Transcript>`, own renderer over `planTranscript`, own everything over
+ * `invokeTurn`) without a cliff. Every prop beyond the connection
+ * essentials is optional.
+ *
+ * ## Composer state matrix
+ *
+ * - `endpointUrl === null` → input disabled, `composerUnavailable`
+ *   placeholder (chat cannot exist).
+ * - idle (`status === "ready"`) → input enabled; **Send** enabled iff the
+ *   input has non-whitespace text.
+ * - in flight (any other status, cold-start waits included — R12's status
+ *   line owns the WHY) → input stays enabled (type the next message while
+ *   the agent works), Send is replaced by **Stop**, which aborts the turn
+ *   (partial text kept, "Stopped." marked — the hook's contract).
+ * - Enter sends; Shift+Enter inserts a newline; an IME-composing Enter
+ *   never sends (the candidate commit is not a submit).
+ *
+ * ## History
+ *
+ * Thread rehydration is the HOOK's mechanics: give `adapters` a `history`
+ * 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.
+ */
+import { useCallback, useMemo, useState } from "react";
+import { createWebAdapters } from "@guuey/agent-client";
+import { useAgentInvoke } from "@guuey/agent-client/react";
+import { calmPolicy, debugPolicy } from "../policy.js";
+import { defaultChatStrings } from "../strings.js";
+import { DEFAULT_CHAT_THEME } from "../theme.js";
+import { Transcript } from "./transcript.js";
+import { useTranscript, useTranscriptInputs } from "./use-transcript.js";
+const PROMPT_STATE = {
+    accept: "answered",
+    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;
+    const adapters = useMemo(() => adaptersProp ?? createWebAdapters(), [adaptersProp]);
+    const invoke = useAgentInvoke({ endpointUrl, ...(appId !== undefined ? { appId } : {}), adapters, preserveBlocks: true });
+    const policy = useMemo(() => {
+        const factory = preset === "debug" ? debugPolicy : calmPolicy;
+        const strings = {
+            ...defaultChatStrings,
+            ...policyOverrides?.strings,
+            ...stringOverrides,
+        };
+        return factory({ ...policyOverrides, strings });
+    }, [preset, policyOverrides, stringOverrides]);
+    const { inputs, resolvePrompt } = useTranscriptInputs(invoke);
+    const { plan, toggle, resolvedMounts, onViewPhase } = useTranscript({
+        inputs,
+        policy,
+        ...(reader !== undefined ? { reader } : {}),
+    });
+    // ── Composer ─────────────────────────────────────────────────────────
+    const [input, setInput] = useState("");
+    const busy = invoke.status !== "ready";
+    const available = endpointUrl !== null;
+    const canSend = available && !busy && input.trim() !== "";
+    const submit = useCallback(() => {
+        const text = input.trim();
+        if (text === "" || !available || busy)
+            return;
+        setInput("");
+        void invoke.send(text).catch(() => {
+            // The hook surfaces the failure (`error` / R0 failed-send).
+        });
+    }, [input, available, busy, invoke]);
+    const handleRetry = useCallback((item) => {
+        void invoke.send(item.text).catch(() => {
+            // Same contract as submit: the hook owns failure surfacing.
+        });
+    }, [invoke]);
+    const handlePromptAction = useCallback((item, action) => {
+        resolvePrompt(item.promptId, PROMPT_STATE[action]);
+        onPromptAction?.(item, action);
+    }, [resolvePrompt, 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) => {
+                            // `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) {
+                                e.preventDefault();
+                                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/markdown.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The R1 markdown surface — the ONE place `@guuey/chat` renders
+ * agent-influenced content in the embedder's origin, and therefore the
+ * package's sanitizer boundary (spec §3.1).
+ *
+ * The pipeline is `@silverprotocol/richtext`: markdown → a TYPED AST in
+ * which raw HTML is structurally unrepresentable (no HTML node type
+ * exists; angle brackets can only ever be literal text) → React elements.
+ * That is deliberately STRONGER than the spec's letter (markdown → HTML →
+ * sanitize): there is no HTML string at any point, so there is nothing to
+ * sanitize incorrectly — no `dangerouslySetInnerHTML` anywhere in this
+ * package.
+ *
+ * Safety properties, each pinned by a test:
+ *  - raw HTML (`<img onerror=…>`, `<script>`) renders as literal text;
+ *  - link `href` is populated upstream ONLY for http/https/mailto —
+ *    `javascript:`, `data:`, `vbscript:`, and relative targets parse as
+ *    styled text with NO anchor `href` (richtext's `SAFE_HREF` allowlist);
+ *  - navigable links carry `rel="noopener noreferrer" target="_blank"`;
+ *  - there is NO image syntax in the node vocabulary at all — the spec's
+ *    F5 ruling (markdown images off; R7 media blocks are the sanctioned
+ *    image path) holds structurally, not by configuration.
+ *
+ * Streaming-tolerant by upstream design: unclosed emphasis mid-delta
+ * renders as formatted-so-far.
+ */
+import type { ReactNode } from "react";
+/** Sanitized markdown → React elements (see the module docblock). */
+export declare function Markdown({ text }: {
+    text: string;
+}): ReactNode;
+//# sourceMappingURL=markdown.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/react/markdown.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AA8EvC,qEAAqE;AACrE,wBAAgB,QAAQ,CAAC,EAAE,IAAI,EAAE,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAQ9D"}

package/dist/react/markdown.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { parseRichText, } from "@silverprotocol/richtext";
+function Inline({ nodes }) {
+    return nodes.map((node, i) => {
+        switch (node.type) {
+            case "text":
+                return _jsx("span", { children: node.text }, i);
+            case "break":
+                return _jsx("br", {}, i);
+            case "strong":
+                return (_jsx("strong", { children: _jsx(Inline, { nodes: node.children }) }, i));
+            case "em":
+                return (_jsx("em", { children: _jsx(Inline, { nodes: node.children }) }, i));
+            case "code":
+                return (_jsx("code", { className: "guuey-chat-inline-code", children: node.code }, i));
+            case "link":
+                return node.href ? (_jsx("a", { href: node.href, target: "_blank", rel: "noopener noreferrer", children: _jsx(Inline, { nodes: node.children }) }, i)) : (
+                // Unsafe or unresolvable target: the styled text, no anchor.
+                _jsx("span", { className: "guuey-chat-dead-link", children: _jsx(Inline, { nodes: node.children }) }, i));
+        }
+    });
+}
+function Block({ block }) {
+    switch (block.type) {
+        case "paragraph":
+            return (_jsx("p", { children: _jsx(Inline, { nodes: block.children }) }));
+        case "heading":
+            return (_jsx("p", { className: `guuey-chat-heading${block.level <= 3 ? " guuey-chat-heading-major" : ""}`, children: _jsx(Inline, { nodes: block.children }) }));
+        case "code-fence":
+            return _jsx("pre", { className: "guuey-chat-code-fence", children: block.code });
+        case "list": {
+            const Tag = block.ordered ? "ol" : "ul";
+            return (_jsx(Tag, { ...(block.ordered && block.start !== undefined ? { start: block.start } : {}), children: block.items.map((item, j) => (_jsx("li", { children: _jsx(Inline, { nodes: item.children }) }, j))) }));
+        }
+    }
+}
+/** Sanitized markdown → React elements (see the module docblock). */
+export function Markdown({ text }) {
+    return (_jsx(_Fragment, { children: parseRichText(text).map((block, i) => (_jsx(Block, { block: block }, i))) }));
+}

package/dist/react/theme-css.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The CSS projection of `GuueyChatTheme` (spec §6): the schema is the
+ * cross-platform contract; this maps one mode's tokens onto the
+ * `--guuey-chat-*` custom properties the shipped stylesheet consumes. RN
+ * (3c) maps the same object to style values instead — no CSS here is
+ * load-bearing for the view-model.
+ */
+import type { GuueyChatTheme } from "../theme.js";
+export type ThemeMode = "light" | "dark";
+/**
+ * One mode's tokens as inline custom properties for the transcript root.
+ * Returned as a plain record so callers can spread it into `style` or emit
+ * a stylesheet from it.
+ */
+export declare function themeCssVars(theme: GuueyChatTheme, mode: ThemeMode): Record<string, string>;
+//# sourceMappingURL=theme-css.d.ts.map

package/dist/react/theme-css.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-css.d.ts","sourceRoot":"","sources":["../../src/react/theme-css.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;AAazC;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAsB3F"}

package/dist/react/theme-css.js

@@ -0,0 +1,37 @@
+const RADIUS_PX = {
+    none: "0px",
+    soft: "10px",
+    round: "18px",
+};
+const DENSITY_GAP = {
+    compact: "6px",
+    comfortable: "10px",
+};
+/**
+ * One mode's tokens as inline custom properties for the transcript root.
+ * Returned as a plain record so callers can spread it into `style` or emit
+ * a stylesheet from it.
+ */
+export function themeCssVars(theme, mode) {
+    const palette = theme.colors[mode];
+    const vars = {
+        "--guuey-chat-accent": palette.accent,
+        "--guuey-chat-on-accent": palette.onAccent,
+        "--guuey-chat-ink": palette.ink,
+        "--guuey-chat-ink-muted": palette.inkMuted,
+        "--guuey-chat-surface": palette.surface,
+        "--guuey-chat-canvas": palette.canvas,
+        "--guuey-chat-canvas-muted": palette.canvasMuted,
+        "--guuey-chat-error": palette.error,
+        "--guuey-chat-radius": RADIUS_PX[theme.shape.radius],
+        "--guuey-chat-gap": DENSITY_GAP[theme.shape.density],
+        "--guuey-chat-scale": String(theme.typography.scale ?? 1),
+    };
+    if (theme.typography.fontFamily !== undefined) {
+        vars["--guuey-chat-font"] = theme.typography.fontFamily;
+    }
+    if (theme.typography.monoFontFamily !== undefined) {
+        vars["--guuey-chat-mono-font"] = theme.typography.monoFontFamily;
+    }
+    return vars;
+}

package/dist/react/transcript.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `<Transcript>` — the plan walker + the §3.2 renderer obligations:
+ *
+ *  - **Scroll contract:** stick-to-bottom while content grows UNLESS the
+ *    user scrolled up, in which case a "jump to latest" affordance appears
+ *    instead; anchoring holds through content resize (a ResizeObserver on
+ *    the item column re-pins — R6 cards growing on `connected` are the
+ *    canonical breaker). `prefers-reduced-motion` downgrades smooth
+ *    scrolling to instant.
+ *  - **Windowing:** long transcripts render the trailing `window.tail`
+ *    items with a "show earlier" expander — the DOM is capped even though
+ *    the plan (already O(groups)) carries everything; the plan's stable
+ *    keys keep expansion state and DOM identity across the window edge.
+ *  - Theme: the resolved `GuueyChatTheme` is projected as `--guuey-chat-*`
+ *    custom properties on the root (import `@guuey/chat/styles.css` once
+ *    for the default look, or restyle the class names entirely).
+ */
+import { type CSSProperties, type ReactNode } from "react";
+import { type GuueyChatTheme } from "../theme.js";
+import { type ChatStrings } from "../strings.js";
+import type { TranscriptPlan } from "../types.js";
+import { type TranscriptComponents, type TranscriptItemContext } from "./components.js";
+import { type ThemeMode } from "./theme-css.js";
+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"> {
+    plan: TranscriptPlan;
+    /** Per-slot component overrides (spec §3's override column). */
+    components?: Partial<TranscriptComponents>;
+    /** The i18n seam — pass the same strings the policy carries. */
+    strings?: ChatStrings;
+    theme?: GuueyChatTheme;
+    mode?: ThemeMode;
+    /** DOM windowing (§3.2). `false` renders everything. Default tail 80. */
+    window?: TranscriptWindowing | false;
+    className?: string;
+    style?: CSSProperties;
+}
+export declare function Transcript(props: TranscriptProps): ReactNode;
+//# sourceMappingURL=transcript.d.ts.map

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

@@ -0,0 +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"}

package/dist/react/transcript.js

@@ -0,0 +1,88 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * `<Transcript>` — the plan walker + the §3.2 renderer obligations:
+ *
+ *  - **Scroll contract:** stick-to-bottom while content grows UNLESS the
+ *    user scrolled up, in which case a "jump to latest" affordance appears
+ *    instead; anchoring holds through content resize (a ResizeObserver on
+ *    the item column re-pins — R6 cards growing on `connected` are the
+ *    canonical breaker). `prefers-reduced-motion` downgrades smooth
+ *    scrolling to instant.
+ *  - **Windowing:** long transcripts render the trailing `window.tail`
+ *    items with a "show earlier" expander — the DOM is capped even though
+ *    the plan (already O(groups)) carries everything; the plan's stable
+ *    keys keep expansion state and DOM identity across the window edge.
+ *  - Theme: the resolved `GuueyChatTheme` is projected as `--guuey-chat-*`
+ *    custom properties on the root (import `@guuey/chat/styles.css` once
+ *    for the default look, or restyle the class names entirely).
+ */
+import { useEffect, useLayoutEffect, useMemo, useRef, useState, } from "react";
+import { DEFAULT_CHAT_THEME } from "../theme.js";
+import { defaultChatStrings } from "../strings.js";
+import { defaultTranscriptComponents, renderItem, } from "./components.js";
+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 resolvedComponents = useMemo(() => ({ ...defaultTranscriptComponents, ...components }), [components]);
+    const ctx = useMemo(() => ({ strings, onToggle, onRetry, onPromptAction, onErrorAction, resolvedMounts, onViewPhase, viewProps }), [strings, onToggle, onRetry, onPromptAction, onErrorAction, resolvedMounts, onViewPhase, viewProps]);
+    // ── Windowing ────────────────────────────────────────────────────────
+    const [extraShown, setExtraShown] = useState(0);
+    const tail = windowing === false ? Number.POSITIVE_INFINITY : windowing.tail;
+    const visibleFrom = Math.max(0, plan.items.length - tail - extraShown);
+    const hidden = visibleFrom;
+    const visible = plan.items.slice(visibleFrom);
+    // ── Scroll contract ──────────────────────────────────────────────────
+    const scroller = useRef(null);
+    const column = useRef(null);
+    const pinned = useRef(true);
+    const [showJump, setShowJump] = useState(false);
+    const reducedMotion = () => typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+    const scrollToBottom = (smooth) => {
+        const el = scroller.current;
+        if (el === null)
+            return;
+        if (typeof el.scrollTo === "function") {
+            el.scrollTo({ top: el.scrollHeight, behavior: smooth && !reducedMotion() ? "smooth" : "auto" });
+        }
+        else {
+            // Environments without Element.scrollTo (jsdom; ancient WebViews).
+            el.scrollTop = el.scrollHeight;
+        }
+    };
+    const onScroll = () => {
+        const el = scroller.current;
+        if (el === null)
+            return;
+        const nearBottom = el.scrollHeight - el.scrollTop - el.clientHeight < PIN_THRESHOLD_PX;
+        pinned.current = nearBottom;
+        setShowJump(!nearBottom);
+    };
+    // New content while pinned keeps the bottom in view (before paint, so
+    // per-frame streaming updates never visibly jump).
+    useLayoutEffect(() => {
+        if (pinned.current)
+            scrollToBottom(false);
+    }, [plan]);
+    // Content RESIZE (an R6 card connecting and growing, an image loading)
+    // re-pins too — scrollHeight changes with no plan change.
+    useEffect(() => {
+        const el = column.current;
+        if (el === null || typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(() => {
+            if (pinned.current)
+                scrollToBottom(false);
+        });
+        observer.observe(el);
+        return () => observer.disconnect();
+    }, []);
+    const rootStyle = { ...themeCssVars(theme, mode), ...style };
+    const StatusComponent = resolvedComponents.status;
+    return (_jsxs("div", { className: `guuey-chat${className !== undefined ? ` ${className}` : ""}`, style: rootStyle, "data-guuey-chat-mode": mode, children: [_jsx("div", { ref: scroller, className: "guuey-chat-scroller", onScroll: onScroll, children: _jsxs("div", { ref: column, className: "guuey-chat-column", children: [hidden > 0 ? (_jsx("button", { type: "button", className: "guuey-chat-show-earlier", onClick: () => setExtraShown((n) => n + tail), children: strings.showEarlier(hidden) })) : null, visible.map((item) => renderItem(item, resolvedComponents, ctx)), plan.status !== null ? (_jsx(StatusComponent, { item: plan.status, ctx: ctx })) : null] }) }), showJump ? (_jsx("button", { type: "button", className: "guuey-chat-jump", onClick: () => {
+                    pinned.current = true;
+                    setShowJump(false);
+                    scrollToBottom(true);
+                }, children: strings.jumpToLatest })) : null] }));
+}

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

@@ -0,0 +1,39 @@
+import type { UseAgentInvokeReturn } from "@guuey/agent-client";
+import { type ResolvedViewMount, type UiResourceReader, type ViewHostPhase } from "@guuey/mcp-apps-host";
+import type { TranscriptPolicy } from "../policy.js";
+import type { ItemKey, TranscriptInputs, TranscriptOverrides, TranscriptPlan } from "../types.js";
+export interface UseTranscriptArgs {
+    inputs: TranscriptInputs;
+    policy: TranscriptPolicy;
+    /**
+     * Resolves R6 `locator` mounts (history cards persisted as `ui://`
+     * identities) with a fresh authenticated `resources/read`. Without one,
+     * locators render the R13 "view expired" state after a failed local
+     * resolution — labeled, never blank.
+     */
+    reader?: UiResourceReader;
+}
+export interface UseTranscriptResult {
+    plan: TranscriptPlan;
+    /** Flip one item's collapse state (wired to every toggle's onClick). */
+    toggle: (key: ItemKey) => void;
+    /** The live collapse-override map (renderer-owned, plan input). */
+    overrides: TranscriptOverrides;
+    /** Wire to `<GuueyView onPhaseChange>` (the default kit already does). */
+    onViewPhase: (key: ItemKey, phase: ViewHostPhase) => void;
+    /** Locator resolutions: mount material, or `"expired"` for a miss. */
+    resolvedMounts: ReadonlyMap<ItemKey, ResolvedViewMount | "expired">;
+}
+export declare function useTranscript({ inputs, policy, reader }: UseTranscriptArgs): UseTranscriptResult;
+export interface UseTranscriptInputsResult {
+    inputs: TranscriptInputs;
+    /**
+     * Record the user's action on an R10 prompt (the host performs the
+     * actual grant/decline through its own channel; this moves the
+     * transcript record). A pending prompt whose hook-side request vanishes
+     * without a recorded action reads as `dismissed`.
+     */
+    resolvePrompt: (id: string, state: "answered" | "declined" | "dismissed") => void;
+}
+export declare function useTranscriptInputs(invoke: UseAgentInvokeReturn): UseTranscriptInputsResult;
+//# sourceMappingURL=use-transcript.d.ts.map

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

@@ -0,0 +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"}

package/dist/react/use-transcript.js

@@ -0,0 +1,201 @@
+/**
+ * The renderer-state owner + the LIVE input assembler (spec §7).
+ *
+ * `planTranscript` is pure — everything stateful about rendering lives
+ * here, in renderer-owned React state:
+ *
+ *  - `useTranscript` owns the user's collapse overrides, the live
+ *    `ViewHostPhase` reports, and locator-mount resolution, merges them
+ *    into the inputs, and returns the (memoized) plan;
+ *  - `useTranscriptInputs` assembles `TranscriptInputs` from
+ *    `useAgentInvoke`'s return — the live twin of the root export's
+ *    `transcriptInputsFromHistory`.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { resolveViewMount, } from "@guuey/mcp-apps-host";
+import { planTranscript } from "../plan.js";
+export function useTranscript({ inputs, policy, reader }) {
+    const [overrides, setOverrides] = useState({});
+    const [phases, setPhases] = useState({});
+    const [resolvedMounts, setResolvedMounts] = useState(new Map());
+    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
+    // previous override) — read from the plan so the first toggle of a
+    // default-expanded item collapses it.
+    const planRef = useRef(plan);
+    planRef.current = plan;
+    const toggle = useCallback((key) => {
+        const findExpanded = () => {
+            for (const item of planRef.current.items) {
+                if (item.key === key)
+                    return item.expanded;
+                if (item.kind === "tool-group") {
+                    for (const tool of item.tools) {
+                        if (tool.key === key)
+                            return tool.expanded;
+                        if (tool.result?.key === key)
+                            return tool.result.expanded;
+                    }
+                }
+                if (item.kind === "tool" && item.result?.key === key)
+                    return item.result.expanded;
+            }
+            return false;
+        };
+        const current = findExpanded();
+        setOverrides((prev) => ({ ...prev, [key]: { expanded: !current } }));
+    }, []);
+    const onViewPhase = useCallback((key, phase) => {
+        setPhases((prev) => (prev[key] === phase ? prev : { ...prev, [key]: phase }));
+    }, []);
+    // Locator resolution — one read per locator key, misses become "expired".
+    const readerRef = useRef(reader);
+    readerRef.current = reader;
+    const inFlight = useRef(new Set());
+    useEffect(() => {
+        for (const item of plan.items) {
+            if (item.kind !== "view")
+                continue;
+            if (item.mount === null || item.mount.channel !== "locator")
+                continue;
+            if (resolvedMounts.has(item.key) || inFlight.current.has(item.key))
+                continue;
+            const read = readerRef.current;
+            const locator = item.mount;
+            inFlight.current.add(item.key);
+            const settle = (value) => {
+                inFlight.current.delete(item.key);
+                setResolvedMounts((prev) => {
+                    const next = new Map(prev);
+                    next.set(item.key, value);
+                    return next;
+                });
+            };
+            if (read === undefined) {
+                settle("expired");
+                continue;
+            }
+            void resolveViewMount(locator, read).then((resolved) => settle(resolved ?? "expired"), () => settle("expired"));
+        }
+    }, [plan, resolvedMounts]);
+    return { plan, toggle, overrides, onViewPhase, resolvedMounts };
+}
+/** How often the escalation clock ticks while a status needs one. */
+const ELAPSED_TICK_MS = 500;
+export function useTranscriptInputs(invoke) {
+    // §4: the elapsed clock is a view-model INPUT — this is the renderer-side
+    // timer that feeds it. Reset on every status change; ticking only while a
+    // status line is showing (R12 escalation + debug detail).
+    const [elapsedMs, setElapsedMs] = useState(0);
+    useEffect(() => {
+        setElapsedMs(0);
+        if (invoke.status === "ready" || invoke.status === "responding")
+            return;
+        const startedAt = Date.now();
+        const timer = setInterval(() => setElapsedMs(Date.now() - startedAt), ELAPSED_TICK_MS);
+        return () => clearInterval(timer);
+    }, [invoke.status]);
+    // R10 ledger: the hook exposes only the LATEST pending ask; the
+    // transcript keeps the record of every ask and its resolution.
+    const [prompts, setPrompts] = useState([]);
+    const promptSeq = useRef(0);
+    useEffect(() => {
+        const request = invoke.profileConsentRequest;
+        if (request === null) {
+            setPrompts((prev) => prev.some((p) => p.kind === "consent" && p.state === "pending")
+                ? prev.map((p) => p.kind === "consent" && p.state === "pending" ? { ...p, state: "dismissed" } : p)
+                : prev);
+            return;
+        }
+        setPrompts((prev) => {
+            if (prev.some((p) => p.kind === "consent" && p.state === "pending"))
+                return prev;
+            return [
+                ...prev,
+                {
+                    id: `consent.${promptSeq.current++}`,
+                    kind: "consent",
+                    appId: request.appId,
+                    requested: request.requested,
+                    state: "pending",
+                },
+            ];
+        });
+    }, [invoke.profileConsentRequest]);
+    useEffect(() => {
+        const request = invoke.profileLinkRequest;
+        if (request === null) {
+            setPrompts((prev) => prev.some((p) => p.kind === "link" && p.state === "pending")
+                ? prev.map((p) => p.kind === "link" && p.state === "pending" ? { ...p, state: "dismissed" } : p)
+                : prev);
+            return;
+        }
+        setPrompts((prev) => {
+            if (prev.some((p) => p.kind === "link" && p.state === "pending"))
+                return prev;
+            return [
+                ...prev,
+                {
+                    id: `link.${promptSeq.current++}`,
+                    kind: "link",
+                    appId: request.appId,
+                    requested: request.requested,
+                    state: "pending",
+                },
+            ];
+        });
+    }, [invoke.profileLinkRequest]);
+    const resolvePrompt = useCallback((id, state) => {
+        setPrompts((prev) => prev.map((p) => (p.id === id ? { ...p, state } : p)));
+        // Clearing the hook's pending request AFTER the ledger moved keeps the
+        // dismissal effect above from double-transitioning it.
+        const pending = prompts.find((p) => p.id === id);
+        if (pending?.kind === "consent")
+            invoke.clearProfileConsentRequest();
+        if (pending?.kind === "link")
+            invoke.clearProfileLinkRequest();
+    }, [invoke, prompts]);
+    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
+        // `assistantText` so the plan can mark it streaming/stopped; settled
+        // turns stay in `messages`.
+        const inFlight = invoke.status !== "ready";
+        let messages = invoke.messages;
+        let assistantText = "";
+        const last = messages[messages.length - 1];
+        if (last !== undefined && last.role === "assistant" && (inFlight || invoke.aborted)) {
+            assistantText = last.text;
+            messages = messages.slice(0, -1);
+        }
+        return {
+            result: invoke.reduceResult,
+            assistantText,
+            status: invoke.status,
+            statusElapsedMs: elapsedMs,
+            activeTool: invoke.activeTool,
+            error: invoke.error !== null ? { message: invoke.error, code: invoke.errorCode } : null,
+            prompts,
+            messages,
+            ...(invoke.historyCards.length > 0 ? { historyCards: invoke.historyCards } : {}),
+            sendStates: invoke.sendStates,
+            aborted: invoke.aborted,
+            adopted: invoke.adopted,
+        };
+    }, [
+        invoke.messages,
+        invoke.status,
+        invoke.activeTool,
+        invoke.error,
+        invoke.errorCode,
+        invoke.reduceResult,
+        invoke.historyCards,
+        invoke.sendStates,
+        invoke.aborted,
+        invoke.adopted,
+        elapsedMs,
+        prompts,
+    ]);
+    return { inputs, resolvePrompt };
+}

package/dist/react.d.ts

@@ -0,0 +1,21 @@
+/**
+ * React entry point (`@guuey/chat/react`) — the component kit over the
+ * root subpath's headless view-model (wave 3b, guuey#135).
+ *
+ * The root subpath stays React-free forever; everything React-coupled —
+ * the per-category components, `<Transcript>`, the renderer-state owner
+ * (`useTranscript`), and the live input assembler (`useTranscriptInputs`)
+ * — lives behind this arm, with `react` as an optional peer (the
+ * mcp-apps-host precedent).
+ *
+ * Composition ladder (spec §1 "configurable"): use `<Transcript>` with the
+ * default kit as-is → override per-category components → tune policy knobs
+ * → 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 { useTranscript, useTranscriptInputs, type UseTranscriptArgs, type UseTranscriptResult, type UseTranscriptInputsResult, } from "./react/use-transcript.js";
+export { GuueyChat, type GuueyChatProps } 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