@teaflask/assistant 0.0.0 → 0.3.0

package/dist/components/suspension-surfaces.js

@@ -0,0 +1,205 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
+import { ApprovalCard } from "./approval-card.js";
+import { ApprovalsContext } from "./approval-context.js";
+import { ElicitationsContext } from "./elicitation-context.js";
+import { TfButton } from "./primitives/button.js";
+import { QuestionPanel } from "./question-panel.js";
+import { SurfaceBoundary } from "./surface-boundary.js";
+import { clampedCursorOf, decisionKeyOf, suspensionQueueOf, } from "../core/suspension-queue.js";
+// The suspension slot's tenant: the ONE actionable surface for the
+// conversation's pending decisions, between the transcript and the
+// composer. The landlord contract (docs/activity-shelf-slot-contract.md)
+// binds the structure: the root carries data-tf-shelf-item, renders null
+// with nothing to decide (the :empty collapse — expression-only children),
+// stays in normal flow, and wears hairline borders only. The ONE sanctioned
+// tenant scroll region is the decision scroll well: a viewport-relative
+// bound around the current card alone (TVC-067, the Scroll-Well Rule) — the
+// queue bar stays outside it, the fold cue shows only while more is below,
+// and its listeners watch only its own region. One decision renders at a
+// time; a package-owned queue bar ("Decision 2 of 3") keeps every one
+// reachable in core/suspension-queue.ts's order, and paging never answers
+// anything. Focus moves only at member-initiated moments — the FOCUS
+// PREMISE is in docs/transcript-surfaces.md.
+export function SuspensionSurfaces({ rowIndexByToolCallId, }) {
+    const { cards } = useContext(ApprovalsContext);
+    const { cards: elicitationCards } = useContext(ElicitationsContext);
+    const queue = useMemo(() => suspensionQueueOf(cards, elicitationCards, rowIndexByToolCallId), [cards, elicitationCards, rowIndexByToolCallId]);
+    const queueKeys = useMemo(() => queue.map(decisionKeyOf), [queue]);
+    const { position, current, currentKey, currentWrapRef, previousButtonRef, nextButtonRef, pagePrevious, pageNext, } = useDecisionQueueHold(queue, queueKeys);
+    const { scrollWellRef, foldBelow, declareFold } = useScrollWellFold(currentKey);
+    const { captureConversationScope, noteFocusWithin, noteBlur } = useDecisionFocusReturn(queueKeys, currentKey, currentWrapRef);
+    if (current === null) {
+        return null;
+    }
+    return (_jsxs("section", { ref: captureConversationScope, "data-tf-shelf-item": "", "data-tf-suspension-surfaces": "", "aria-label": "Pending decisions", className: "tf:w-full", onFocus: noteFocusWithin, onBlur: noteBlur, children: [queue.length > 1 ? (_jsxs("div", { "data-tf-suspension-pager": "", className: "tf:flex tf:items-center tf:justify-between tf:gap-2 tf:pb-1 tf:text-tf-label tf:text-tf-muted-foreground", children: [_jsx("span", { children: `Decision ${String(position + 1)} of ${String(queue.length)}` }), _jsxs("span", { className: "tf:flex tf:gap-1", children: [_jsx(TfButton, { ref: previousButtonRef, variant: "ghost", disabled: position === 0, onClick: pagePrevious, children: "Previous" }), _jsx(TfButton, { ref: nextButtonRef, variant: "ghost", disabled: position === queue.length - 1, onClick: pageNext, children: "Next" })] })] })) : null, _jsx("div", { ref: scrollWellRef, "data-tf-decision-scroll-well": "", "data-tf-fold-below": foldBelow ? "" : undefined, className: "tf:overflow-y-auto tf:overscroll-contain", onScroll: declareFold, children: _jsx("div", { ref: currentWrapRef, "data-tf-current-decision": "", tabIndex: -1, className: "tf:outline-none", children: _jsx(SurfaceBoundary, { surface: "decision-card", children: current.kind === "approval" ? (_jsx(ApprovalCard, { card: current.card })) : (_jsx(QuestionPanel, { card: current.card })) }) }, currentKey) })] }));
+}
+// THE PRESENTED-DECISION HOLD: the current decision is held by IDENTITY
+// (a queue key in state); the numeric index is only the fallback for the
+// moment that identity leaves the queue. A new arrival can reorder the
+// queue or land on a stale index, and the held KEY still names the same
+// decision, so the presented card never swaps or remounts under a
+// mid-review member. It changes only when the member pages or the held
+// decision resolves — then the NEXT decision at the same position is promoted.
+function useDecisionQueueHold(queue, queueKeys) {
+    const [hold, setHold] = useState({ key: null, position: 0 });
+    const heldIndex = hold.key === null ? -1 : queueKeys.indexOf(hold.key);
+    const position = heldIndex >= 0 ? heldIndex : clampedCursorOf(hold.position, queue.length);
+    const current = queue.length === 0 ? null : queue[position];
+    const currentKey = current === null ? null : decisionKeyOf(current);
+    // Adopt the presented decision as the hold — the guarded
+    // adjust-state-during-render idiom (React discards this render's
+    // output and restarts with the settled value), so a reorder has
+    // re-pointed nothing by the time anything paints and no effect ever
+    // races the adoption.
+    if (currentKey !== hold.key || position !== hold.position) {
+        setHold({ key: currentKey, position });
+    }
+    const currentWrapRef = useRef(null);
+    const previousButtonRef = useRef(null);
+    const nextButtonRef = useRef(null);
+    // A pager press that LANDS on an end disables the pressed button while
+    // it holds focus, and a browser blurs a disabled element to nowhere —
+    // dropping the member to the top of the document and (via the
+    // section's onBlur with a null relatedTarget) disarming the resolve
+    // hand-off. The landing press therefore requests focus for the
+    // sibling, honored AFTER the re-render — at click time the sibling
+    // may itself still be disabled (the two-decision case).
+    const pendingPagerFocusRef = useRef(null);
+    useEffect(() => {
+        if (pendingPagerFocusRef.current === "previous") {
+            previousButtonRef.current?.focus();
+        }
+        else if (pendingPagerFocusRef.current === "next") {
+            nextButtonRef.current?.focus();
+        }
+        pendingPagerFocusRef.current = null;
+    });
+    return {
+        position,
+        current,
+        currentKey,
+        currentWrapRef,
+        previousButtonRef,
+        nextButtonRef,
+        pagePrevious: () => {
+            const target = clampedCursorOf(position - 1, queue.length);
+            setHold({ key: queueKeys[target] ?? null, position: target });
+            if (target === 0) {
+                pendingPagerFocusRef.current = "next";
+            }
+        },
+        pageNext: () => {
+            const target = clampedCursorOf(position + 1, queue.length);
+            setHold({ key: queueKeys[target] ?? null, position: target });
+            if (target === queue.length - 1) {
+                pendingPagerFocusRef.current = "previous";
+            }
+        },
+    };
+}
+/** The declared fold (the Scroll-Well Rule): true while more of the
+ *  current decision sits below the well's visible bottom. */
+function useScrollWellFold(currentKey) {
+    const scrollWellRef = useRef(null);
+    const [foldBelow, setFoldBelow] = useState(false);
+    const declareFold = useCallback(() => {
+        const well = scrollWellRef.current;
+        if (well === null) {
+            return;
+        }
+        setFoldBelow(well.scrollHeight - well.scrollTop - well.clientHeight > 1);
+    }, []);
+    useEffect(() => {
+        const well = scrollWellRef.current;
+        if (well === null) {
+            return;
+        }
+        // A newly presented decision starts at its top — the consent reading
+        // begins at the title, never mid-payload where the last one left off.
+        well.scrollTop = 0;
+        declareFold();
+        // The well's content changes height without scrolling (for example,
+        // a deny textarea appearing) — watch the
+        // content itself so the cue stays honest. Own-region observation
+        // only; the transcript's follow machinery is never touched.
+        const content = well.firstElementChild;
+        if (!(content instanceof HTMLElement) ||
+            typeof ResizeObserver === "undefined") {
+            return;
+        }
+        const observer = new ResizeObserver(() => {
+            declareFold();
+        });
+        observer.observe(content);
+        return () => {
+            observer.disconnect();
+        };
+    }, [currentKey, declareFold]);
+    return { scrollWellRef, foldBelow, declareFold };
+}
+/** Where focus goes when the decision under it resolves: the next
+ *  presented decision's wrapper, or — the queue emptied — THIS
+ *  conversation's composer input. */
+function useDecisionFocusReturn(queueKeys, currentKey, currentWrapRef) {
+    // Whether focus currently lives inside the tenant — tracked by the
+    // focus events themselves, because by the time an unmount effect runs
+    // the browser has already dropped focus to <body> silently.
+    const focusWithinRef = useRef(false);
+    // THIS conversation's column, captured while the tenant is mounted so the
+    // queue-empties hand-off can still find the composer after this component
+    // returns null. Scoped to the closest [data-tf-conversation]: surfaces
+    // mount Transcript CONCURRENTLY (the page under an open palette), and a
+    // document-scoped query would resolve the FIRST composer — inert behind
+    // the modal. The root node is only the fallback for bare hosts.
+    const conversationScopeRef = useRef(null);
+    const previousKeyRef = useRef(null);
+    useEffect(() => {
+        const previousKey = previousKeyRef.current;
+        previousKeyRef.current = currentKey;
+        if (previousKey === null) {
+            return;
+        }
+        const currentDecisionLeft = !queueKeys.includes(previousKey);
+        if (!currentDecisionLeft || !focusWithinRef.current) {
+            return;
+        }
+        if (currentKey !== null) {
+            currentWrapRef.current?.focus();
+            return;
+        }
+        // The queue emptied under the member's focus: hand it back to THIS
+        // conversation's composer input (the scope captured above — same
+        // column, shadow-root safe, never another surface's composer).
+        focusWithinRef.current = false;
+        const composerInput = conversationScopeRef.current?.querySelector("[data-tf-composer-wash] textarea");
+        composerInput?.focus();
+    }, [queueKeys, currentKey, currentWrapRef]);
+    return {
+        captureConversationScope: (node) => {
+            if (node !== null) {
+                conversationScopeRef.current =
+                    node.closest("[data-tf-conversation]") ??
+                        node.getRootNode();
+            }
+        },
+        noteFocusWithin: () => {
+            focusWithinRef.current = true;
+        },
+        noteBlur: (event) => {
+            // Disarm ONLY when focus verifiably moved outside the tenant. A null
+            // relatedTarget is a blur to NOWHERE — the browser's disable-blur fixup
+            // on our own controls (the double-click guard) or a window blur — where
+            // the hand-off must stay armed. Accepted residual: a click on a
+            // non-focusable page area also blurs to nowhere, so a later resolve
+            // re-anchors focus onto the decision region. Seam enumeration: the
+            // decision-surface coverage record.
+            if (event.relatedTarget !== null &&
+                !event.currentTarget.contains(event.relatedTarget)) {
+                focusWithinRef.current = false;
+            }
+        },
+    };
+}
+//# sourceMappingURL=suspension-surfaces.js.map

package/dist/components/suspension-surfaces.js.map

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

package/dist/components/teaflask-assistant-provider.d.ts

@@ -0,0 +1,135 @@
+import { type ReactNode } from "react";
+import { type AssistantTheme, type AssistantThemeMode } from "../appearance/theme.js";
+import type { ActionsAdapter } from "../contract/actions-adapter.js";
+import type { ServedAttachmentPolicy, ServedModelChoice, ServedSuggestionsConfig } from "../contract/assistant-config.js";
+import type { VisitorTier } from "../contract/identity.js";
+import type { SubscriptionStatus } from "../contract/subscriptions.js";
+import type { AssistantTelemetryEvent } from "../contract/telemetry.js";
+import type { ConversationGate } from "../core/connect-gate.js";
+import type { ReadonlyCell } from "../core/observable-cell.js";
+import type { AssistantConversationStore } from "../core/conversation-store.js";
+import type { ExecuteActionIntent, HostNavigate } from "../core/execution-handlers.js";
+import type { ServingApiError } from "../transport/serving-error.js";
+import type { TokenSession } from "../transport/token-session.js";
+import type { ToolViewRegistry } from "../core/tool-view.js";
+import type { AssistantSuggestionInput } from "./conversation-view.js";
+export interface TeaflaskAssistantProviderProps {
+    publishableKey: string;
+    baseUrl?: string;
+    getEndUserToken?: () => string | null | Promise<string | null>;
+    /**
+     * How this page performs the actions the org's catalog grants (the
+     * http_intent execution request) — see the ActionsAdapter contract.
+     * Absent means this surface cannot perform actions: the assistant is
+     * told so in-band and tells the user what to do themselves.
+     */
+    actionsAdapter?: ActionsAdapter;
+    /**
+     * How this page takes the visitor to an app-relative path when the
+     * assistant asks (the builtin.navigate execution request). Absent means
+     * this surface cannot navigate: the assistant is told so in-band. May be
+     * async; resolve once the navigation has been handed to the host's router.
+     */
+    onNavigate?: (path: string) => void | Promise<void>;
+    onError?: (error: Error) => void;
+    /**
+     * Observer for the package's product-telemetry events — the approval
+     * submit path's attempted/sent/dropped narration, for hosts that
+     * forward product analytics (the dashboard sends these to PostHog).
+     * Distinct from onError on purpose: these are events, not failures,
+     * and most carry no exception.
+     */
+    onTelemetry?: (event: AssistantTelemetryEvent) => void;
+    /**
+     * JS theming over the same 21 public tokens as the CSS route, in
+     * camelCase (`primaryForeground` sets `--tf-primary-foreground`), plus a
+     * nested `dark` variant. Values land as inline style variables on the
+     * widget roots, so an explicit prop beats ambient host CSS. Read by value
+     * — a fresh literal every render never resets conversation state. Inline
+     * styles need `style-src 'unsafe-inline'` (or `style-src-attr`) under a strict CSP; theme
+     * through the CSS route instead if that is not allowed.
+     */
+    theme?: AssistantTheme;
+    /**
+     * Writes `data-tf-theme` on the widget roots: `"dark"` pins the dark
+     * palette, `"light"` pins light even under an ancestor's dark
+     * attribute, `"auto"` follows the visitor's OS preference (a CSS media
+     * query — no script runs). Omit it and the attribute stays the host's
+     * to manage on any ancestor.
+     */
+    mode?: AssistantThemeMode;
+    /**
+     * Your own companion mark, rendered on the corner perch and the
+     * drawer's welcome inside one box the package sizes (4rem on both).
+     * The package sets your node to 100% width and height of that box, so
+     * a bare `<svg viewBox>` or `<img>` fills it without sizing itself;
+     * keep the artwork's aspect inside the viewBox. A
+     * sibling of `theme` on purpose — the mark is identity, not a theme
+     * token. Read by identity like `toolViews`. Omit it for the TeaFlask
+     * flask in the foreground color — `flag && <Mark />` on its false arm
+     * counts as omitted, like every host fill in the package.
+     */
+    companionMark?: ReactNode;
+    /**
+     * Opening prompts for the companion drawer's first-run welcome. A bare
+     * string renders as an `ask`; `{ prompt, kind }` picks the glyph. Read by
+     * value like `theme`. Omit it and the drawer serves the prompts authored
+     * on the organization's assistant, matched to the page's path. Passing
+     * any value — even `[]` — overrides the served sets wholesale, never
+     * merges: explicit JS intent beats remote config.
+     */
+    suggestions?: readonly AssistantSuggestionInput[];
+    /**
+     * The trusted-host tool-view registry (tool-views.md): adapters this
+     * host compiled and deployed, keyed by the opaque namespaced key a
+     * backend display annotation may name (rung 1: exact key AND version)
+     * or by the host's own exact tool name (rung 2). A registration carries
+     * a view, an icon, or both; absence, mismatch, or a throw falls to the
+     * rung below, terminally the package default view. Adapters receive
+     * exactly `ToolViewProps` — never stores, tokens, or transport, and never
+     * approve/deny. `teaflask.*` keys are reserved for package built-ins.
+     * Read by identity but never memo-keyed: a fresh literal every render
+     * never resets conversation state (registries should still live at
+     * module scope — the mount slot keys the adapter lifecycle on identity).
+     */
+    toolViews?: ToolViewRegistry;
+    children?: ReactNode;
+}
+interface AssistantSessionValue {
+    session: TokenSession;
+    store: AssistantConversationStore;
+    publishableKey: string;
+    identityProvided: boolean;
+    navigate: HostNavigate | null;
+    executeActionIntent: ExecuteActionIntent | null;
+    tier: VisitorTier | null;
+    setupError: ServingApiError | null;
+    assistantConfig: ReadonlyCell<ServedSuggestionsConfig | null>;
+    attachmentPolicy: ReadonlyCell<ServedAttachmentPolicy | null>;
+    modelChoice: ReadonlyCell<ServedModelChoice | null>;
+    configAnswered: ReadonlyCell<boolean>;
+    ensureAssistantConfig: () => void;
+    refreshAssistantConfig: () => void;
+    conversationGate: ReadonlyCell<ConversationGate>;
+    subscriptions: ReadonlyCell<SubscriptionStatus[] | null>;
+    ensureSubscriptions: () => void;
+    refreshSubscriptions: () => void;
+    connectOpenRequested: ReadonlyCell<boolean>;
+    requestSubscriptionConnect: () => void;
+    acknowledgeSubscriptionConnect: () => void;
+    reportError: (error: Error) => void;
+}
+export declare function useAssistantSession(): AssistantSessionValue;
+/** The tolerant read for components with a degraded no-session rendering
+ *  (the composer's paperclip, an attachment's inline image) — outside the
+ *  provider they hide the affordance instead of throwing, which is also
+ *  what lets welcome-branch tests render the view bare. */
+export declare function useOptionalAssistantSession(): AssistantSessionValue | null;
+/**
+ * Owns the visitor-token session and the identity handshake. Deliberately
+ * no visitorToken, data, or agent props — the package speaks only the
+ * public contract (each of those would be a dogfood escape hatch).
+ */
+export declare function TeaflaskAssistantProvider({ publishableKey, baseUrl, getEndUserToken, actionsAdapter, onNavigate, onError, onTelemetry, theme, mode, companionMark, suggestions, toolViews, children, }: TeaflaskAssistantProviderProps): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=teaflask-assistant-provider.d.ts.map

package/dist/components/teaflask-assistant-provider.d.ts.map

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

package/dist/components/teaflask-assistant-provider.js

@@ -0,0 +1,230 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, } from "react";
+import { themeToStyleVars, } from "../appearance/theme.js";
+import { assistantSessionRegistry, } from "../core/assistant-session-registry.js";
+import { hostFillDeclines } from "../core/host-fill.js";
+import { performActionIntent } from "../transport/actions-adapter.js";
+import { AssistantAppearanceContext, } from "./appearance-context.js";
+import { ToolViewRegistryContext } from "./tool-view-registry-context.js";
+import { ConversationSurfacesProvider } from "./conversation-surfaces-provider.js";
+import { useCell } from "./use-store-cell.js";
+const AssistantSessionContext = createContext(null);
+export function useAssistantSession() {
+    const value = useContext(AssistantSessionContext);
+    if (value === null) {
+        throw new Error("Teaflask assistant components must be rendered inside <TeaflaskAssistantProvider>.");
+    }
+    return value;
+}
+/** The tolerant read for components with a degraded no-session rendering
+ *  (the composer's paperclip, an attachment's inline image) — outside the
+ *  provider they hide the affordance instead of throwing, which is also
+ *  what lets welcome-branch tests render the view bare. */
+export function useOptionalAssistantSession() {
+    return useContext(AssistantSessionContext);
+}
+/**
+ * Owns the visitor-token session and the identity handshake. Deliberately
+ * no visitorToken, data, or agent props — the package speaks only the
+ * public contract (each of those would be a dogfood escape hatch).
+ */
+export function TeaflaskAssistantProvider({ publishableKey, baseUrl, getEndUserToken, actionsAdapter, onNavigate, onError, onTelemetry, theme, mode, companionMark, suggestions, toolViews, children, }) {
+    const host = useHostCallbackRefs({
+        getEndUserToken,
+        actionsAdapter,
+        onNavigate,
+        onError,
+        onTelemetry,
+    });
+    const value = useSessionRegistration({ publishableKey, baseUrl, host });
+    const appearance = useAppearanceValue({
+        theme,
+        mode,
+        companionMark,
+        suggestions,
+    });
+    return (_jsx(AssistantSessionContext.Provider, { value: value, children: _jsx(AssistantAppearanceContext.Provider, { value: appearance, children: _jsx(ToolViewRegistryContext.Provider, { value: toolViews ?? null, children: _jsx(ConversationSurfacesProvider, { store: value.store, children: children }) }) }) }));
+}
+/** The host's callbacks behind identity-stable wrappers, so hosts that
+ *  pass inline arrows never disturb the session or the store. */
+function useHostCallbackRefs({ getEndUserToken, actionsAdapter, onNavigate, onError, onTelemetry, }) {
+    // Latest-callback refs keep the TokenSession identity stable across
+    // re-renders that only changed the closures (hosts often pass inline
+    // arrows). Updated in an effect per the hooks lint law.
+    const getEndUserTokenRef = useRef(getEndUserToken);
+    const actionsAdapterRef = useRef(actionsAdapter);
+    const onNavigateRef = useRef(onNavigate);
+    const onErrorRef = useRef(onError);
+    const onTelemetryRef = useRef(onTelemetry);
+    useEffect(() => {
+        getEndUserTokenRef.current = getEndUserToken;
+        actionsAdapterRef.current = actionsAdapter;
+        onNavigateRef.current = onNavigate;
+        onErrorRef.current = onError;
+        onTelemetryRef.current = onTelemetry;
+    });
+    const identityProvided = getEndUserToken !== undefined;
+    const actionsProvided = actionsAdapter !== undefined;
+    const navigationProvided = onNavigate !== undefined;
+    const resolveEndUserToken = useCallback(() => getEndUserTokenRef.current?.() ?? null, []);
+    const hostNavigate = useCallback(async (path) => {
+        await onNavigateRef.current?.(path);
+    }, []);
+    const executeActionIntent = useCallback((intent) => performActionIntent(_wiredAdapterOf(actionsAdapterRef.current), intent), []);
+    const reportError = useCallback((error) => {
+        onErrorRef.current?.(error);
+    }, []);
+    const recordTelemetry = useCallback((event) => {
+        onTelemetryRef.current?.(event);
+    }, []);
+    const telemetryProvided = onTelemetry !== undefined;
+    // What this page can execute, read fresh by the store at each execution
+    // pass — hosts re-wire navigation/actions across renders and the store's
+    // identity must not depend on theirs.
+    const hostCapabilitiesRef = useRef({
+        navigate: null,
+        executeActionIntent: null,
+    });
+    useEffect(() => {
+        hostCapabilitiesRef.current = {
+            navigate: navigationProvided ? hostNavigate : null,
+            executeActionIntent: actionsProvided ? executeActionIntent : null,
+        };
+    });
+    const hostCapabilitiesOf = useCallback(() => hostCapabilitiesRef.current, []);
+    return {
+        identityProvided,
+        actionsProvided,
+        navigationProvided,
+        telemetryProvided,
+        resolveEndUserToken,
+        hostNavigate,
+        executeActionIntent,
+        reportError,
+        recordTelemetry,
+        hostCapabilitiesOf,
+    };
+}
+/** Resolves the shared session entry, holds it retained for the mounted
+ *  lifetime, and shapes the context value every surface reads. */
+function useSessionRegistration({ publishableKey, baseUrl, host, }) {
+    const { identityProvided, actionsProvided, navigationProvided, telemetryProvided, resolveEndUserToken, hostNavigate, executeActionIntent, reportError, recordTelemetry, hostCapabilitiesOf, } = host;
+    // The registry resolves the session's identity inputs to ONE shared
+    // TokenSession + store pair — same-identity providers, even in other
+    // React roots (two custom elements on one host page), converse through
+    // the same store. Render-safe: entryFor only constructs, never boots.
+    const entry = useMemo(() => assistantSessionRegistry.entryFor({
+        publishableKey,
+        baseUrl,
+        identityProvided,
+    }), [publishableKey, baseUrl, identityProvided]);
+    const session = entry.session;
+    const store = entry.store;
+    // This provider's wiring rides the entry for exactly the mounted
+    // lifetime: the first retain boots the store, the last release
+    // disposes store and session (the registry's ref-count replaces the
+    // per-provider dispose that lived here).
+    useEffect(() => {
+        const registrant = {
+            resolveEndUserToken: identityProvided ? resolveEndUserToken : null,
+            hostCapabilitiesOf,
+            reportError,
+            onTelemetry: telemetryProvided ? recordTelemetry : null,
+        };
+        return assistantSessionRegistry.retain(entry, registrant);
+    }, [
+        entry,
+        identityProvided,
+        resolveEndUserToken,
+        hostCapabilitiesOf,
+        reportError,
+        telemetryProvided,
+        recordTelemetry,
+    ]);
+    // The mint's verdict lives on the entry, not in provider state: a
+    // provider mounting after the mint answered reads the cached verdict
+    // instead of waiting for a mint that already happened.
+    const tier = useCell(entry.tier);
+    const setupError = useCell(entry.setupError);
+    return useMemo(() => ({
+        session,
+        store,
+        publishableKey,
+        identityProvided,
+        navigate: navigationProvided ? hostNavigate : null,
+        executeActionIntent: actionsProvided ? executeActionIntent : null,
+        tier,
+        setupError,
+        assistantConfig: entry.assistantConfig,
+        attachmentPolicy: entry.attachmentPolicy,
+        modelChoice: entry.modelChoice,
+        configAnswered: entry.configAnswered,
+        ensureAssistantConfig: entry.ensureAssistantConfig,
+        refreshAssistantConfig: entry.refreshAssistantConfig,
+        conversationGate: entry.conversationGate,
+        subscriptions: entry.subscriptions,
+        ensureSubscriptions: entry.ensureSubscriptions,
+        refreshSubscriptions: entry.refreshSubscriptions,
+        connectOpenRequested: entry.connectOpenRequested,
+        requestSubscriptionConnect: entry.requestSubscriptionConnect,
+        acknowledgeSubscriptionConnect: entry.acknowledgeSubscriptionConnect,
+        reportError,
+    }), [
+        session,
+        store,
+        publishableKey,
+        identityProvided,
+        navigationProvided,
+        hostNavigate,
+        actionsProvided,
+        executeActionIntent,
+        tier,
+        setupError,
+        entry,
+        reportError,
+    ]);
+}
+/** A host's mark, or null for the package flask — the fall-through rule
+ *  (core/host-fill.ts): the idiomatic `companionMark={flag && <Mark />}`
+ *  gets the flask on its false arm; renderable emptiness is the host's
+ *  deliberate content. Folded once, here, because CompanionMark branches
+ *  on null. */
+function _companionMarkOf(companionMark) {
+    return hostFillDeclines(companionMark) ? null : companionMark;
+}
+/** The theme and suggestions props travel by value, not identity: hosts
+ *  write both as inline literals. Serializing once and keying the memo on
+ *  the strings keeps those identities out of every dependency array here.
+ *  The companion mark is the exception — a ReactNode has no value form,
+ *  so it rides by identity, like toolViews. */
+function useAppearanceValue({ theme, mode, companionMark, suggestions, }) {
+    const themeJson = theme === undefined ? null : JSON.stringify(theme);
+    const suggestionsJson = suggestions === undefined ? null : JSON.stringify(suggestions);
+    return useMemo(() => {
+        const rootProps = {};
+        if (themeJson !== null) {
+            rootProps.style = themeToStyleVars(JSON.parse(themeJson));
+        }
+        if (mode !== undefined) {
+            rootProps["data-tf-theme"] = mode;
+        }
+        return {
+            rootProps,
+            companionMark: _companionMarkOf(companionMark),
+            suggestions: suggestionsJson === null
+                ? null
+                : JSON.parse(suggestionsJson),
+        };
+    }, [themeJson, mode, companionMark, suggestionsJson]);
+}
+// The context value only exposes the executor when the adapter prop is
+// present, so an empty ref here is a package bug, not a host mistake —
+// but the narrowing must still be explicit for the lint laws.
+function _wiredAdapterOf(adapter) {
+    if (adapter === undefined) {
+        throw new Error("The actions adapter was removed while an action was executing.");
+    }
+    return adapter;
+}
+//# sourceMappingURL=teaflask-assistant-provider.js.map

package/dist/components/teaflask-assistant-provider.js.map

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

package/dist/components/teaflask-assistant.d.ts

@@ -0,0 +1,29 @@
+import { type AssistantCompanionProps } from "./assistant-companion.js";
+import { type TeaflaskAssistantProviderProps } from "./teaflask-assistant-provider.js";
+export interface TeaflaskAssistantHandle {
+    /**
+     * Opens the palette regardless of the hotkey setting — the imperative
+     * escape hatch for a host that disabled or rebound the chord. Call it
+     * through the ref's optional chain (`ref.current?.openPalette()`): the
+     * handle exists only while the root is mounted, so an early or late
+     * call no-ops instead of throwing. Opening the palette makes the
+     * companion yield (hide) until it closes — by design: the palette
+     * counts as an open assistant surface.
+     */
+    openPalette: () => void;
+}
+export interface TeaflaskAssistantProps extends TeaflaskAssistantProviderProps {
+    /**
+     * The palette chord, "mod+k" by default (mod = ⌘ or Ctrl). Rebind with
+     * the same grammar ("mod+j", "ctrl+shift+p") when your app already
+     * spends ⌘K, or pass false to disable — the ref handle still opens the
+     * palette. An unrecognized spec disables the hotkey with a console
+     * warning rather than falling back: a host rebinding away from a
+     * conflict must never be silently rebound into it.
+     */
+    hotkey?: string | false;
+    /** The viewport corner the companion (and its drawer) anchor to. */
+    corner?: AssistantCompanionProps["corner"];
+}
+export declare const TeaflaskAssistant: import("react").ForwardRefExoticComponent<TeaflaskAssistantProps & import("react").RefAttributes<TeaflaskAssistantHandle>>;
+//# sourceMappingURL=teaflask-assistant.d.ts.map

package/dist/components/teaflask-assistant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"teaflask-assistant.d.ts","sourceRoot":"","sources":["../../src/components/teaflask-assistant.tsx"],"names":[],"mappings":"AAiBA,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAEL,KAAK,8BAA8B,EACpC,MAAM,kCAAkC,CAAC;AAe1C,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;OAQG;IACH,WAAW,EAAE,MAAM,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,sBAAuB,SAAQ,8BAA8B;IAC5E;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACxB,oEAAoE;IACpE,MAAM,CAAC,EAAE,uBAAuB,CAAC,QAAQ,CAAC,CAAC;CAC5C;AAKD,eAAO,MAAM,iBAAiB,4HAmD5B,CAAC"}