@teaflask/assistant 0.3.0 → 0.6.0

package/dist/components/subscription-connected-standing.d.ts

@@ -1,12 +1,16 @@
 import type { SubscriptionStatus } from "../contract/subscriptions.js";
-/** The connected standing: the provider's mark, plan and state chip, the
- *  disclosure line, the standing sentence when not active, the reconnect
- *  action for a bounced credential, and the disconnect behind the chip. */
-export declare function ConnectedStanding({ name, status, errorSentence, onReconnect, onDisconnect, }: {
+interface ConnectOutcome {
+    headline: string;
+    detail: string;
+}
+export declare function ConnectedStanding({ name, status, errorSentence, outcome, rechecking, onRecheck, onReconnect, onDisconnect, }: {
     name: string;
     status: SubscriptionStatus;
     errorSentence: string | null;
+    outcome: ConnectOutcome | null;
+    rechecking: boolean;
+    onRecheck: () => void;
     onReconnect: () => void;
     onDisconnect: () => void;
 }): import("react").JSX.Element;
-//# sourceMappingURL=subscription-connected-standing.d.ts.map
+export {};

package/dist/components/subscription-connected-standing.js

@@ -1,62 +1,71 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from "react";
-import { humanizedWait } from "../core/error-copy.js";
 import { ChevronDownIcon, OpenAiMarkIcon } from "./icons.js";
 import { TfButton } from "./primitives/button.js";
-/** The connected standing: the provider's mark, plan and state chip, the
- *  disclosure line, the standing sentence when not active, the reconnect
- *  action for a bounced credential, and the disconnect behind the chip. */
-export function ConnectedStanding({ name, status, errorSentence, onReconnect, onDisconnect, }) {
+import { checkingPlanSentenceOf, HeartbeatLine, ManageUsageLink, notEligibleSentenceOf, planLimitSentenceOf, } from "./subscription-connect-arms.js";
+export function ConnectedStanding({ name, status, errorSentence, outcome, rechecking, onRecheck, onReconnect, onDisconnect, }) {
     const [actionsOpen, setActionsOpen] = useState(false);
     const actionsId = `tf-provider-actions-${status.provider}`;
     const active = status.state === "active";
     return (_jsxs("div", { className: "tf:flex tf:flex-col tf:gap-3", children: [_jsx(ConnectedStandingHeader, { name: name, status: status, actionsOpen: actionsOpen, actionsId: actionsId, onToggleActions: () => {
                     setActionsOpen((current) => !current);
-                } }), _jsxs("p", { className: "tf:m-0 tf:text-xs tf:text-tf-muted-foreground", children: ["Uses your ", name, " plan's included usage."] }), active ? null : (_jsx("p", { className: "tf:m-0 tf:text-tf-label tf:text-tf-foreground", role: "status", children: standingSentenceOf(name, status) })), status.offered ? null : (_jsxs("p", { className: "tf:m-0 tf:text-tf-label tf:text-tf-muted-foreground", children: [name, " sign-in is no longer offered here."] })), status.state === "bounced" && status.offered ? (_jsxs(TfButton, { variant: "primary", className: "tf:self-start", onClick: onReconnect, children: ["Reconnect ", name] })) : null, errorSentence === null ? null : (
-            // Same announcement law as the connect arm's error line.
-            _jsx("p", { className: "tf:m-0 tf:text-tf-label tf:text-tf-destructive", role: "alert", children: errorSentence })), actionsOpen ? (_jsx("div", { id: actionsId, className: "tf:flex tf:justify-end tf:border-t tf:pt-2", children: _jsxs(TfButton, { variant: "outline", onClick: onDisconnect, children: ["Disconnect ", name] }) })) : null] }));
+                } }), status.state === "bounced" ? null : (_jsxs("p", { className: "tf:m-0 tf:text-xs tf:text-tf-muted-foreground", children: ["Uses your ", name, " plan's included usage."] })), _jsx(StandingLine, { name: name, status: status, outcome: outcome, active: active }), status.offered ? null : (_jsxs("p", { className: "tf:m-0 tf:text-tf-label tf:text-tf-muted-foreground", children: [name, " sign-in is no longer offered here."] })), status.state === "bounced" && rechecking ? (_jsx(HeartbeatLine, { sentence: checkingPlanSentenceOf(name) })) : status.state === "bounced" ? (_jsx(BouncedRemedy, { name: name, status: status, onRecheck: onRecheck, onReconnect: onReconnect })) : null, errorSentence === null ? null : (_jsx("p", { className: "tf:m-0 tf:text-tf-label tf:text-tf-destructive", role: "alert", children: errorSentence })), actionsOpen ? (_jsxs("div", { id: actionsId, className: "tf:flex tf:flex-wrap tf:justify-end tf:gap-2 tf:border-t tf:pt-2", children: [status.bounce_cause === "quota" ? null : (_jsx(ManageUsageLink, { provider: status.provider, variant: "outline" })), _jsxs(TfButton, { variant: "outline", onClick: onDisconnect, children: ["Disconnect ", name] })] })) : null] }));
+}
+function StandingLine({ name, status, outcome, active, }) {
+    if (outcome !== null) {
+        return (_jsxs("div", { className: "tf:flex tf:flex-col tf:gap-1", role: "status", children: [_jsx("p", { className: "tf:m-0 tf:text-tf-label tf:font-medium tf:text-tf-foreground", children: outcome.headline }), _jsx("p", { className: "tf:m-0 tf:text-tf-label tf:text-tf-muted-foreground", children: outcome.detail })] }));
+    }
+    if (active) {
+        return null;
+    }
+    if (status.state === "verifying") {
+        return (_jsx(HeartbeatLine, { sentence: standingSentenceOf(name, status), tone: "foreground" }));
+    }
+    return (_jsx("p", { className: "tf:m-0 tf:text-tf-label tf:text-tf-foreground", role: "status", children: standingSentenceOf(name, status) }));
+}
+function BouncedRemedy({ name, status, onRecheck, onReconnect, }) {
+    if (status.bounce_cause === "quota") {
+        return (_jsxs("div", { className: "tf:flex tf:flex-wrap tf:items-center tf:gap-2", children: [_jsx(ManageUsageLink, { provider: status.provider }), status.offered ? (_jsx(TfButton, { variant: "outline", onClick: onRecheck, children: "Check again" })) : null] }));
+    }
+    if (!status.offered) {
+        return null;
+    }
+    return (_jsxs(TfButton, { variant: "primary", className: "tf:self-start", onClick: onReconnect, children: ["Reconnect ", name] }));
 }
-/** The standing's header row: the provider's mark and plan beside the
- *  state chip that toggles the actions row. */
 function ConnectedStandingHeader({ name, status, actionsOpen, actionsId, onToggleActions, }) {
-    const plan = status.plan_type;
-    return (_jsxs("div", { className: "tf:flex tf:items-center tf:justify-between tf:gap-3", children: [_jsxs("div", { className: "tf:flex tf:min-w-0 tf:items-center tf:gap-2.5", children: [_jsx("span", { className: "tf:flex tf:size-8 tf:shrink-0 tf:items-center tf:justify-center tf:rounded-full tf:bg-tf-muted tf:text-tf-foreground", children: _jsx(OpenAiMarkIcon, {}) }), _jsxs("div", { className: "tf:flex tf:min-w-0 tf:flex-col", children: [_jsx("span", { className: "tf:truncate tf:text-tf-label tf:font-medium tf:text-tf-foreground", children: name }), _jsx("span", { className: "tf:truncate tf:text-xs tf:text-tf-muted-foreground", children: plan === null ? "AI subscription" : `${_titleCased(plan)} plan` })] })] }), _jsxs(TfButton, { variant: "outline", className: "tf:shrink-0", "aria-expanded": actionsOpen, "aria-controls": actionsId, onClick: onToggleActions, children: [_jsx("span", { "aria-hidden": true, className: status.state === "bounced"
-                            ? "tf:size-1.5 tf:rounded-full tf:bg-tf-destructive"
-                            : "tf:size-1.5 tf:rounded-full tf:bg-tf-foreground" }), status.state === "verifying"
-                        ? "Verifying"
-                        : status.state === "bounced"
-                            ? "Reconnect"
-                            : "Connected", _jsx(ChevronDownIcon, {})] })] }));
+    return (_jsxs("div", { className: "tf:flex tf:items-center tf:justify-between tf:gap-3", children: [_jsxs("div", { className: "tf:flex tf:min-w-0 tf:items-center tf:gap-2.5", children: [_jsx("span", { className: "tf:flex tf:size-8 tf:shrink-0 tf:items-center tf:justify-center tf:rounded-full tf:bg-tf-muted tf:text-tf-foreground", children: _jsx(OpenAiMarkIcon, {}) }), _jsxs("div", { className: "tf:flex tf:min-w-0 tf:flex-col", children: [_jsx("span", { className: "tf:truncate tf:text-tf-label tf:font-medium tf:text-tf-foreground", children: name }), _jsx("span", { className: "tf:truncate tf:text-xs tf:text-tf-muted-foreground", children: "AI subscription" })] })] }), _jsxs(TfButton, { variant: "outline", className: "tf:shrink-0", "aria-expanded": actionsOpen, "aria-controls": actionsId, onClick: onToggleActions, children: [_jsx("span", { "aria-hidden": true, className: stateDotClassOf(status) }), stateChipLabelOf(status), _jsx(ChevronDownIcon, {})] })] }));
 }
-/** The standing, as one sentence. A bounced credential names which
- *  recovery helps off the read's own cause: a quota bounce heals
- *  with time, an auth bounce by reconnecting. */
-function standingSentenceOf(name, status) {
-    if (status.state === "verifying") {
-        return `Verifying your ${name} connection…`;
+function stateDotClassOf(status) {
+    if (status.state === "bounced" && status.bounce_cause !== "quota") {
+        return "tf:size-1.5 tf:rounded-full tf:bg-tf-destructive";
     }
     if (status.state === "bounced") {
-        return status.bounce_cause === "quota"
-            ? `Your ${name} plan's included usage is used up${_untilItsReset(status)}.`
-            : `Your ${name} connection stopped working.`;
-    }
-    const plan = status.plan_type;
-    return plan === null
-        ? `Connected to ${name}.`
-        : `Connected — ${_titleCased(plan)} plan.`;
+        return "tf:size-1.5 tf:rounded-full tf:bg-tf-muted-foreground";
+    }
+    return "tf:size-1.5 tf:rounded-full tf:bg-tf-foreground";
 }
-function _untilItsReset(status) {
-    if (status.bounce_retry_at === null) {
-        return "";
+function stateChipLabelOf(status) {
+    if (status.state === "verifying") {
+        return "Verifying";
     }
-    const resetMs = Date.parse(status.bounce_retry_at);
-    if (Number.isNaN(resetMs) || resetMs <= Date.now()) {
-        return "";
+    if (status.state === "bounced") {
+        return status.bounce_cause === "quota" ? "Limit reached" : "Reconnect";
     }
-    return ` — it resets in about ${humanizedWait((resetMs - Date.now()) / 1000)}`;
+    return "Connected";
 }
-function _titleCased(plan) {
-    return plan.charAt(0).toUpperCase() + plan.slice(1);
+function standingSentenceOf(name, status) {
+    if (status.state === "verifying") {
+        return `Verifying your ${name} connection…`;
+    }
+    if (status.state === "bounced") {
+        if (status.bounce_cause === "quota") {
+            return planLimitSentenceOf(name);
+        }
+        if (status.bounce_cause === "not_eligible") {
+            return notEligibleSentenceOf(name);
+        }
+        return `Your ${name} connection stopped working.`;
+    }
+    return `Connected to ${name}.`;
 }
-//# sourceMappingURL=subscription-connected-standing.js.map

package/dist/components/subscription-plan-notice.d.ts

@@ -0,0 +1 @@
+export declare function SubscriptionPlanNotice(): import("react").JSX.Element | null;

package/dist/components/subscription-plan-notice.js

@@ -0,0 +1,29 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { readPlanNoticeSeen, writePlanNoticeSeen, } from "../persistence/plan-notice.js";
+import { OpenAiMarkIcon } from "./icons.js";
+import { TfButton } from "./primitives/button.js";
+import { manageUsageUrlOf } from "./subscription-connect-arms.js";
+import { providerNameOf } from "./subscription-connect-flow.js";
+import { useAssistantSession } from "./teaflask-assistant-provider.js";
+import { useCell } from "./use-store-cell.js";
+export function SubscriptionPlanNotice() {
+    const session = useAssistantSession();
+    const due = useCell(session.planNoticeDue);
+    const statuses = useCell(session.subscriptions);
+    if (due === null) {
+        return null;
+    }
+    const standing = statuses?.find((status) => Object.is(status.provider, due));
+    const active = standing?.connected === true && standing.state === "active";
+    if (!active || readPlanNoticeSeen(session.publishableKey, due)) {
+        return null;
+    }
+    const name = providerNameOf(due);
+    const manageUsageUrl = manageUsageUrlOf(due);
+    const dismiss = () => {
+        writePlanNoticeSeen(session.publishableKey, due);
+        session.acknowledgePlanNotice();
+    };
+    return (_jsxs("div", { className: "tf:mb-3 tf:flex tf:flex-col tf:gap-2 tf:rounded-xl tf:bg-tf-accent tf:p-3", role: "status", children: [_jsxs("p", { className: "tf:m-0 tf:flex tf:items-center tf:gap-2 tf:text-tf-label tf:font-medium tf:text-tf-foreground", children: [_jsx(OpenAiMarkIcon, {}), "You're using your ", name, " plan"] }), _jsxs("p", { className: "tf:m-0 tf:text-tf-label tf:text-tf-muted-foreground", children: ["Eligible usage in this app uses your ", name, " plan.", " ", manageUsageUrl === null ? (_jsxs(_Fragment, { children: ["Manage usage in your ", name, " settings."] })) : (_jsxs(_Fragment, { children: [_jsx("a", { href: manageUsageUrl, target: "_blank", rel: "noopener noreferrer", className: "tf:text-tf-foreground tf:underline tf:underline-offset-2", children: "Manage usage" }), " ", "in your ", name, " settings."] }))] }), _jsx(TfButton, { variant: "primary", className: "tf:self-start", onClick: dismiss, children: "Got it" })] }));
+}

package/dist/components/subscription-recheck.d.ts

@@ -0,0 +1,10 @@
+import type { SubscriptionStatus } from "../contract/subscriptions.js";
+import type { TokenSession } from "../transport/token-session.js";
+interface SubscriptionRecheckControl {
+    rechecking: boolean;
+    errorSentence: string | null;
+    recheck: () => void;
+}
+export declare function useRefreshStandingAndGate(): () => void;
+export declare function useSubscriptionRecheck(status: SubscriptionStatus | null, session: TokenSession, refresh: () => void): SubscriptionRecheckControl;
+export {};

package/dist/components/subscription-recheck.js

@@ -0,0 +1,73 @@
+"use client";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { failureSentenceOf } from "../core/error-copy.js";
+import { recheckSubscription } from "../transport/serving-api.js";
+import { pollStanding } from "./standing-poll.js";
+import { useAssistantSession } from "./teaflask-assistant-provider.js";
+export function useRefreshStandingAndGate() {
+    const session = useAssistantSession();
+    return useCallback(() => {
+        session.refreshSubscriptions();
+        session.refreshAssistantConfig();
+    }, [session]);
+}
+export function useSubscriptionRecheck(status, session, refresh) {
+    const [state, setState] = useState({ kind: "idle" });
+    const busyRef = useRef(false);
+    if (state.kind === "settling" && _theRowMovedOn(status, state.anchors)) {
+        setState({ kind: "settled" });
+    }
+    const settled = state.kind === "settled";
+    useEffect(() => {
+        if (settled) {
+            refresh();
+        }
+    }, [settled, refresh]);
+    const settling = state.kind === "settling";
+    useEffect(() => {
+        if (!settling) {
+            return;
+        }
+        return pollStanding(refresh, () => {
+            setState({ kind: "idle" });
+        });
+    }, [settling, refresh]);
+    const recheck = () => {
+        if (busyRef.current || status === null) {
+            return;
+        }
+        busyRef.current = true;
+        setState({ kind: "asking" });
+        void recheckSubscription(session, status.provider)
+            .then(({ standing, probeStarted }) => {
+            refresh();
+            setState(probeStarted
+                ? {
+                    kind: "settling",
+                    anchors: {
+                        echoedHorizon: standing.bounce_retry_at,
+                        askedWith: status,
+                    },
+                }
+                : { kind: "idle" });
+        })
+            .catch((error) => {
+            setState({ kind: "error", sentence: failureSentenceOf(error) });
+        })
+            .finally(() => {
+            busyRef.current = false;
+        });
+    };
+    return {
+        rechecking: state.kind === "asking" || settling,
+        errorSentence: state.kind === "error" ? state.sentence : null,
+        recheck,
+    };
+}
+function _theRowMovedOn(status, anchors) {
+    if (status === anchors.askedWith) {
+        return false;
+    }
+    return (status?.state !== "bounced" ||
+        status.bounce_retry_at !== anchors.echoedHorizon);
+}

package/dist/components/surface-boundary.d.ts

@@ -1,18 +1,8 @@
 import { type ReactNode } from "react";
 export declare function SurfaceBoundary({ surface, shelfItem, degrade, onError, children, }: {
-    /** Which surface this protects — named in the console and carried on
-     *  the fallback's data attribute. */
     surface: string;
-    /** The ActivityShelf slot contract (docs/activity-shelf-slot-contract):
-     *  a tenant's root must carry data-tf-shelf-item — when the boundary
-     *  replaces a shelf tenant, the fallback card is the tenant. */
     shelfItem?: boolean;
-    /** "card" (default) renders the flow-normal fallback; "silent" renders
-     *  nothing — for overlay surfaces whose card would land as a stray
-     *  in-flow block on the host page. Reporting is identical. */
     degrade?: "card" | "silent";
-    /** Test/fixture seam; defaults to the session's reportError. */
     onError?: (error: Error) => void;
     children: ReactNode;
 }): import("react").JSX.Element;
-//# sourceMappingURL=surface-boundary.d.ts.map

package/dist/components/surface-boundary.js

@@ -2,30 +2,14 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Component, } from "react";
 import { useOptionalAssistantSession } from "./teaflask-assistant-provider.js";
-// The surface boundary: every package surface renders behind one, so our
-// bug never unmounts the HOST's tree. Three rules, all held — never
-// swallow, never wrap, degrade to a cascade-independent card (not a
-// blank; overlay mounts opt into "silent"). No reset API: recovery is a
-// remount keyed on this element. Rationale: docs/surface-boundary.md.
 export function SurfaceBoundary({ surface, shelfItem = false, degrade = "card", onError, children, }) {
-    // Tolerant read: the message list and composer also mount in fixtures
-    // and tests with no provider above them — the boundary still degrades
-    // and still names the surface, it just has no host observer to tell.
     const session = useOptionalAssistantSession();
     return (_jsx(SurfaceCatchBoundary, { surface: surface, shelfItem: shelfItem, degrade: degrade, onFailure: onError ?? session?.reportError, children: children }));
 }
-// The card's entire appearance, as literals: a fixed light alert card —
-// white ground, near-black ink, hairline border — legible on ANY host
-// surface, dark pages included. No var() anywhere: a custom property
-// would re-attach the card to whichever tree it lands in.
 const FALLBACK_CARD_STYLE = {
     boxSizing: "border-box",
     display: "block",
     width: "100%",
-    // px, never rem (scripts/rem-to-px.mjs is the repo's standing rule
-    // for the same hazard): a host's html { font-size } must not resize
-    // the one element that exists for the broken state. The matrix's
-    // sixth arm asserts these under a shrunken host root font.
     maxWidth: "768px",
     margin: "8px auto",
     padding: "12px 16px",
@@ -42,13 +26,6 @@ class SurfaceCatchBoundary extends Component {
         return { failed: true };
     }
     componentDidCatch(error, info) {
-        // Every call out of this boundary that host code can supply or
-        // intercept is guarded, because a throw INSIDE componentDidCatch
-        // re-raises to the next boundary up — none, at the chrome roots.
-        // onFailure may throw ANY payload, null included, so a boolean flag
-        // records it (never a value sentinel) and it rides to the console as
-        // an argument, never stringified by us. Out of reach: a callback that
-        // never returns. The enumeration: docs/surface-boundary.md.
         let observerThrew = false;
         let observerError;
         try {
@@ -65,8 +42,6 @@ class SurfaceCatchBoundary extends Component {
             }
         }
         catch {
-            // A throwing console interceptor costs the narration, never the
-            // host's tree.
         }
     }
     render() {
@@ -74,18 +49,8 @@ class SurfaceCatchBoundary extends Component {
             return this.props.children;
         }
         if (this.props.degrade === "silent") {
-            // The overlay surfaces' degradation: absence, exactly what a
-            // closed palette or a yielded companion already renders. The
-            // report above already fired.
             return null;
         }
-        return (_jsx("div", { role: "alert", "data-tf-surface-fallback": this.props.surface, ...(this.props.shelfItem ? { "data-tf-shelf-item": "" } : {}), 
-            // The ruled exception: the degraded card must stay legible
-            // precisely when the widget is broken, so inline literals — the
-            // one mechanism no later stylesheet rule can out-cascade — carry
-            // its whole appearance (tests-e2e/boundary.spec.ts).
-            // eslint-disable-next-line react/forbid-dom-props -- see above
-            style: FALLBACK_CARD_STYLE, children: "This part of the assistant hit an error." }));
+        return (_jsx("div", { role: "alert", "data-tf-surface-fallback": this.props.surface, ...(this.props.shelfItem ? { "data-tf-shelf-item": "" } : {}), style: FALLBACK_CARD_STYLE, children: "This part of the assistant hit an error." }));
     }
 }
-//# sourceMappingURL=surface-boundary.js.map

package/dist/components/suspension-surfaces.d.ts

@@ -1,6 +1,3 @@
 export declare function SuspensionSurfaces({ rowIndexByToolCallId, }: {
-    /** Transcript order for the deterministic queue: the anchoring call's
-     *  display-row index by tool call id. */
     rowIndexByToolCallId: ReadonlyMap<string, number>;
 }): import("react").JSX.Element | null;
-//# sourceMappingURL=suspension-surfaces.d.ts.map

package/dist/components/suspension-surfaces.js

@@ -8,20 +8,6 @@ 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);
@@ -35,37 +21,18 @@ export function SuspensionSurfaces({ rowIndexByToolCallId, }) {
     }
     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") {
@@ -99,8 +66,6 @@ function useDecisionQueueHold(queue, queueKeys) {
         },
     };
 }
-/** 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);
@@ -116,14 +81,8 @@ function useScrollWellFold(currentKey) {
         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") {
@@ -139,20 +98,8 @@ function useScrollWellFold(currentKey) {
     }, [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(() => {
@@ -169,9 +116,6 @@ function useDecisionFocusReturn(queueKeys, currentKey, currentWrapRef) {
             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();
@@ -188,13 +132,6 @@ function useDecisionFocusReturn(queueKeys, currentKey, currentWrapRef) {
             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;
@@ -202,4 +139,3 @@ function useDecisionFocusReturn(queueKeys, currentKey, currentWrapRef) {
         },
     };
 }
-//# sourceMappingURL=suspension-surfaces.js.map

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

@@ -3,7 +3,7 @@ import { type AssistantTheme, type AssistantThemeMode } from "../appearance/them
 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 { SubscriptionProvider, 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";
@@ -13,85 +13,26 @@ 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 {
+export interface TeaflaskAssistantIdentityProps {
+    userId: string;
+    getEndUserToken: () => string | null | Promise<string | null>;
+}
+export interface TeaflaskAssistantAnonymousProps {
+    userId?: undefined;
+    getEndUserToken?: undefined;
+}
+export type TeaflaskAssistantProviderProps = TeaflaskAssistantProviderBaseProps & (TeaflaskAssistantIdentityProps | TeaflaskAssistantAnonymousProps);
+export interface TeaflaskAssistantProviderBaseProps {
     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;
 }
@@ -117,19 +58,12 @@ interface AssistantSessionValue {
     connectOpenRequested: ReadonlyCell<boolean>;
     requestSubscriptionConnect: () => void;
     acknowledgeSubscriptionConnect: () => void;
+    planNoticeDue: ReadonlyCell<SubscriptionProvider | null>;
+    notePlanSignedIn: (provider: SubscriptionProvider) => void;
+    acknowledgePlanNotice: () => 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 declare function TeaflaskAssistantProvider({ publishableKey, baseUrl, userId, getEndUserToken, actionsAdapter, onNavigate, onError, onTelemetry, theme, mode, companionMark, suggestions, toolViews, children, }: TeaflaskAssistantProviderProps): import("react").JSX.Element;
 export {};
-//# sourceMappingURL=teaflask-assistant-provider.d.ts.map