@stigmer/react 0.3.4 → 0.4.0

package/src/github/useGitHubConnection.ts

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { create } from "@bufbuild/protobuf";
 import { EnvironmentSecretValueInputSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/io_pb";
 import { useStigmer } from "../hooks";
@@ -526,16 +526,21 @@ export function useGitHubConnection(
     }
   }, []);
 
-  return {
-    isConnected: token !== null,
-    isLoading,
-    isConnecting,
-    popupBlocked,
-    user,
-    token,
-    connect,
-    handleCallback,
-    reconcile,
-    disconnect,
-  };
+  const isConnected = token !== null;
+
+  return useMemo(
+    () => ({
+      isConnected,
+      isLoading,
+      isConnecting,
+      popupBlocked,
+      user,
+      token,
+      connect,
+      handleCallback,
+      reconcile,
+      disconnect,
+    }),
+    [isConnected, isLoading, isConnecting, popupBlocked, user, token, connect, handleCallback, reconcile, disconnect],
+  );
 }

package/src/identity-account/index.ts

@@ -0,0 +1,5 @@
+export {
+  useIdentityAccountGate,
+  type IdentityAccountGateState,
+  type UseIdentityAccountGateReturn,
+} from "./useIdentityAccountGate";

package/src/identity-account/useIdentityAccountGate.ts

@@ -0,0 +1,163 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { IdentityAccount } from "@stigmer/protos/ai/stigmer/iam/identityaccount/v1/api_pb";
+import { isNotFound } from "@stigmer/sdk";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Discriminated union representing the current state of the identity
+ * account gate.
+ *
+ * Narrow on `status` to access variant-specific data:
+ *
+ * ```ts
+ * if (state.status === "ready") {
+ *   console.log(state.account.metadata?.id);
+ * }
+ * ```
+ */
+export type IdentityAccountGateState =
+  | {
+      /** Resolving the caller's identity account via whoAmI. */
+      readonly status: "checking";
+    }
+  | {
+      /** whoAmI returned NOT_FOUND; provisionMyAccount is in flight. */
+      readonly status: "provisioning";
+    }
+  | {
+      /** Identity account is resolved and available. */
+      readonly status: "ready";
+      /** The resolved identity account. */
+      readonly account: IdentityAccount;
+    }
+  | {
+      /** A non-recoverable error occurred. */
+      readonly status: "error";
+      /** Human-readable failure message suitable for UI display. */
+      readonly message: string;
+    };
+
+/**
+ * Return value of {@link useIdentityAccountGate}.
+ *
+ * `retry` is always available; the consumer invokes it when
+ * `status === "error"`.
+ */
+export interface UseIdentityAccountGateReturn {
+  /** Current gate state. Discriminated union on `status`. */
+  readonly state: IdentityAccountGateState;
+  /** Re-attempt the identity resolution from scratch. */
+  readonly retry: () => void;
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Headless behavior hook that ensures the authenticated caller has an
+ * identity account before the application renders.
+ *
+ * The hook drives the following lifecycle:
+ *
+ * 1. **`checking`** — calls `whoAmI()` to look up the caller's account.
+ * 2. **`provisioning`** — `whoAmI` returned NOT_FOUND (first login after
+ *    signup); the hook calls `provisionMyAccount()` to create the account
+ *    and personal organization.
+ * 3. **`ready`** — an identity account is available (either pre-existing
+ *    or freshly provisioned).
+ * 4. **`error`** — a non-recoverable failure occurred; `message` carries
+ *    the reason. Call `retry()` to restart from step 1.
+ *
+ * The hook is a no-op when `isEnabled` is false — it immediately reports
+ * `ready` with a `null`-account shortcut so that disabled-auth deployments
+ * skip the gate entirely.
+ *
+ * @example
+ * ```tsx
+ * const { state, retry } = useIdentityAccountGate({ isEnabled: true });
+ *
+ * switch (state.status) {
+ *   case "checking":
+ *   case "provisioning":
+ *     return <Spinner />;
+ *   case "ready":
+ *     return <>{children}</>;
+ *   case "error":
+ *     return <ErrorScreen message={state.message} onRetry={retry} />;
+ * }
+ * ```
+ */
+export function useIdentityAccountGate(options: {
+  /** Set to `true` when OIDC auth is active. When `false`, the gate is bypassed. */
+  readonly isEnabled: boolean;
+}): UseIdentityAccountGateReturn {
+  const { isEnabled } = options;
+  const stigmer = useStigmer();
+
+  const [state, setState] = useState<IdentityAccountGateState>(
+    isEnabled ? { status: "checking" } : BYPASSED_STATE,
+  );
+
+  const attemptRef = useRef(0);
+
+  const resolve = useCallback(async () => {
+    const attempt = ++attemptRef.current;
+    setState({ status: "checking" });
+
+    try {
+      const account = await stigmer.identityAccount.whoAmI();
+      if (attempt !== attemptRef.current) return;
+      setState({ status: "ready", account });
+    } catch (whoAmIErr: unknown) {
+      if (attempt !== attemptRef.current) return;
+
+      if (!isNotFound(whoAmIErr)) {
+        setState({ status: "error", message: toError(whoAmIErr).message });
+        return;
+      }
+
+      setState({ status: "provisioning" });
+
+      try {
+        const account = await stigmer.identityAccount.provisionMyAccount();
+        if (attempt !== attemptRef.current) return;
+        setState({ status: "ready", account });
+      } catch (provisionErr: unknown) {
+        if (attempt !== attemptRef.current) return;
+        setState({ status: "error", message: toError(provisionErr).message });
+      }
+    }
+  }, [stigmer]);
+
+  useEffect(() => {
+    if (!isEnabled) {
+      setState(BYPASSED_STATE);
+      return;
+    }
+    resolve();
+  }, [isEnabled, resolve]);
+
+  const retry = useCallback(() => {
+    if (isEnabled) resolve();
+  }, [isEnabled, resolve]);
+
+  return { state, retry };
+}
+
+/**
+ * Sentinel state used when the gate is disabled. The consumer must treat
+ * `status === "ready"` without accessing `account` when auth is disabled
+ * (there is no real identity in that mode).
+ */
+const BYPASSED_STATE: IdentityAccountGateState = Object.freeze({
+  status: "ready",
+  account: null as unknown as IdentityAccount,
+});

package/src/index.ts

@@ -2,6 +2,10 @@
 export { StigmerProvider, type StigmerProviderProps } from "./provider";
 export { StigmerContext } from "./context";
 
+// Fetch cache
+export { FetchCacheProvider } from "./internal/FetchCacheProvider";
+export type { FetchCacheOptions } from "./internal/fetch-cache";
+
 // Hooks
 export { useStigmer } from "./hooks";
 
@@ -139,6 +143,7 @@ export {
   SubAgentSection,
   MessageEntry,
   MessageThread,
+  ThreadSkeleton,
   FollowUpInput,
   ApprovalCard,
   ArtifactCard,
@@ -189,6 +194,7 @@ export type {
   SubAgentSectionProps,
   MessageEntryProps,
   MessageThreadProps,
+  ThreadSkeletonProps,
   FollowUpInputProps,
   ApprovalCardProps,
   ArtifactCardProps,
@@ -417,6 +423,15 @@ export type {
   UseSessionEnvPoolReturn,
 } from "./environment";
 
+// Identity Account — gate hook for ensuring the caller's identity account exists before app render
+export {
+  useIdentityAccountGate,
+} from "./identity-account";
+export type {
+  IdentityAccountGateState,
+  UseIdentityAccountGateReturn,
+} from "./identity-account";
+
 // IAM Policy — data hooks, behavior hooks, headless hook, and styled components for access management
 export {
   useGrantableRoles,
@@ -474,6 +489,53 @@ export type {
   OrgSwitcherProps,
 } from "./organization";
 
+// Billing — data hooks, behavior hooks, styled components, catalog, and formatting utilities
+export {
+  useBillingAccount,
+  useCreditLedger,
+  useBillingUsageReport,
+  useCustomerModelPricing,
+  useCreateCheckoutSession,
+  useCreateBillingPortalSession,
+  useSetAutoRechargeConfig,
+  BillingSection,
+  CreditBalanceCard,
+  PaymentMethodCard,
+  AutoRechargeCard,
+  CreditPackGrid,
+  CreditLedgerTable,
+  LowBalanceBanner,
+  CREDIT_PACKS,
+  formatPackPrice,
+  formatCreditCount,
+  formatCreditBalance,
+  formatLedgerAmount,
+  ledgerEntryLabel,
+  isCredit,
+  isHold,
+  formatLedgerDate,
+} from "./billing";
+export type {
+  UseBillingAccountReturn,
+  UseCreditLedgerReturn,
+  UseCreditLedgerOptions,
+  UseBillingUsageReportReturn,
+  UseCustomerModelPricingReturn,
+  CreateCheckoutSessionInput,
+  UseCreateCheckoutSessionReturn,
+  UseCreateBillingPortalSessionReturn,
+  SetAutoRechargeConfigInput,
+  UseSetAutoRechargeConfigReturn,
+  BillingSectionProps,
+  CreditBalanceCardProps,
+  PaymentMethodCardProps,
+  AutoRechargeCardProps,
+  CreditPackGridProps,
+  CreditLedgerTableProps,
+  LowBalanceBannerProps,
+  CreditPackInfo,
+} from "./billing";
+
 // Settings — navigation structure + section components shared across app shells
 export { SETTINGS_NAV_GROUPS } from "./settings";
 export type { SettingsNavItem, SettingsNavGroup } from "./settings";
@@ -666,6 +728,11 @@ export type {
 export {
   useOrgUsageReport,
   OrgUsagePanel,
+  CreditRunwayIndicator,
+  AgentBreakdownList,
+  HarnessSplitCard,
+  useExportCSV,
+  ExportButton,
   DATE_RANGE_PRESETS,
   dateRangeFromPreset,
   formatDateRange,
@@ -674,6 +741,12 @@ export {
 export type {
   UseOrgUsageReportReturn,
   OrgUsagePanelProps,
+  CreditRunwayIndicatorProps,
+  AgentBreakdownListProps,
+  HarnessSplitCardProps,
+  UseExportCSVReturn,
+  ExportFormat,
+  ExportButtonProps,
   DateRange,
   DateRangePreset,
 } from "./usage";

package/src/internal/FetchCacheProvider.tsx

@@ -0,0 +1,74 @@
+"use client";
+
+import { createContext, useContext, useRef, type ReactNode } from "react";
+import { FetchCache, type FetchCacheOptions } from "./fetch-cache";
+
+// ---------------------------------------------------------------------------
+// Context
+// ---------------------------------------------------------------------------
+
+/**
+ * @internal Exported for test-level injection — not part of the public API.
+ */
+export const FetchCacheContext = createContext<FetchCache | null>(null);
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+/**
+ * Provides a `FetchCache` instance to descendant `useFetch` hooks.
+ *
+ * Mount this component **above** any remount boundary (e.g. above a
+ * `key`-driven session switch) so that cached data survives when child
+ * components unmount and remount. Without this provider, `useFetch`
+ * works exactly as before — no cache, no behavior change.
+ *
+ * @example
+ * ```tsx
+ * // In your app shell (above the session key boundary):
+ * <FetchCacheProvider>
+ *   <SessionPageInner key={activeSessionId} id={activeSessionId} />
+ * </FetchCacheProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom limits:
+ * <FetchCacheProvider maxEntries={50} ttl={120_000}>
+ *   <App />
+ * </FetchCacheProvider>
+ * ```
+ */
+export function FetchCacheProvider({
+  children,
+  maxEntries,
+  ttl,
+}: FetchCacheOptions & { children: ReactNode }) {
+  const cacheRef = useRef<FetchCache | null>(null);
+  if (!cacheRef.current) {
+    cacheRef.current = new FetchCache({ maxEntries, ttl });
+  }
+  return (
+    <FetchCacheContext.Provider value={cacheRef.current}>
+      {children}
+    </FetchCacheContext.Provider>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Access the nearest `FetchCache` from context.
+ *
+ * Returns `null` when no `FetchCacheProvider` is mounted — callers
+ * must handle the null case gracefully (skip caching).
+ *
+ * @internal Consumed by `useFetch`; not intended for direct use by
+ * SDK consumers.
+ */
+export function useFetchCache(): FetchCache | null {
+  return useContext(FetchCacheContext);
+}

package/src/internal/JumpToLatestButton.tsx

@@ -0,0 +1,61 @@
+"use client";
+
+import { cn } from "@stigmer/theme";
+
+interface JumpToLatestButtonProps {
+  readonly onClick: () => void;
+  readonly visible: boolean;
+}
+
+/**
+ * Floating action button that scrolls the thread to the latest content.
+ * Always mounted in the DOM to support enter/exit CSS transitions.
+ * Hidden via opacity + pointer-events when `visible` is false.
+ *
+ * @internal Not part of the public API.
+ */
+export function JumpToLatestButton({ onClick, visible }: JumpToLatestButtonProps) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-label="Jump to latest"
+      aria-hidden={!visible}
+      tabIndex={visible ? 0 : -1}
+      className={cn(
+        "absolute bottom-3 left-1/2 z-10 -translate-x-1/2",
+        "flex items-center gap-1.5 rounded-full",
+        "border border-border bg-card px-3 py-1.5",
+        "text-xs font-medium text-muted-foreground shadow-md",
+        "transition-[opacity,transform] duration-[var(--stgm-motion-duration)]",
+        "hover:bg-muted hover:text-foreground",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        visible
+          ? "pointer-events-auto translate-y-0 opacity-100"
+          : "pointer-events-none translate-y-2 opacity-0",
+      )}
+    >
+      <ChevronDownIcon />
+      Jump to latest
+    </button>
+  );
+}
+
+function ChevronDownIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="m6 9 6 6 6-6" />
+    </svg>
+  );
+}

package/src/internal/ThreadItemWrapper.tsx

@@ -0,0 +1,65 @@
+"use client";
+
+import { useCallback, useRef, useState, type ReactNode } from "react";
+
+interface ThreadItemWrapperProps {
+  readonly animate: boolean;
+  readonly children: ReactNode;
+}
+
+const ANIMATION_CLASS = "stgm-thread-item-enter";
+
+/**
+ * Thin wrapper that applies the `.stgm-thread-item-enter` CSS animation
+ * on mount when `animate` is true. The class is removed after the
+ * animation completes (via `onAnimationEnd`) to free the browser from
+ * tracking a finished animation.
+ *
+ * A fallback timeout removes the class if `animationend` never fires
+ * (e.g. `prefers-reduced-motion` sets duration to ~0ms, or the test
+ * environment doesn't dispatch animation events).
+ *
+ * @internal Not part of the public API.
+ */
+export function ThreadItemWrapper({ animate, children }: ThreadItemWrapperProps) {
+  const [entering, setEntering] = useState(animate);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  const handleAnimationEnd = useCallback(() => {
+    setEntering(false);
+    if (timerRef.current !== undefined) {
+      clearTimeout(timerRef.current);
+      timerRef.current = undefined;
+    }
+  }, []);
+
+  const divRef = useCallback(
+    (node: HTMLDivElement | null) => {
+      if (timerRef.current !== undefined) {
+        clearTimeout(timerRef.current);
+        timerRef.current = undefined;
+      }
+      if (node && entering) {
+        timerRef.current = setTimeout(() => {
+          setEntering(false);
+          timerRef.current = undefined;
+        }, 300);
+      }
+    },
+    [entering],
+  );
+
+  if (!entering) {
+    return children;
+  }
+
+  return (
+    <div
+      ref={divRef}
+      className={ANIMATION_CLASS}
+      onAnimationEnd={handleAnimationEnd}
+    >
+      {children}
+    </div>
+  );
+}

package/src/internal/VirtualizedThread.tsx

@@ -0,0 +1,162 @@
+"use client";
+
+import {
+  forwardRef,
+  useCallback,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentPropsWithRef,
+} from "react";
+import { Virtuoso, type VirtuosoHandle } from "react-virtuoso";
+import { cn } from "@stigmer/theme";
+import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  ThreadItemRenderer,
+  type ThreadItem,
+} from "../execution/MessageThread";
+import { FilePathContext, type FilePathContextValue } from "../execution/FilePathContext";
+import { SandboxContext, type SandboxContextValue } from "../execution/SandboxContext";
+import { DevProfiler, useDomNodeCount } from "./dev";
+import { JumpToLatestButton } from "./JumpToLatestButton";
+import { ThreadItemWrapper } from "./ThreadItemWrapper";
+
+// ---------------------------------------------------------------------------
+// Props
+// ---------------------------------------------------------------------------
+
+export interface VirtualizedThreadProps {
+  readonly items: readonly ThreadItem[];
+  readonly formatToolCallSummary?: (toolCalls: readonly ToolCall[]) => string;
+  readonly onApprovalSubmit?: (
+    toolCallId: string,
+    action: ApprovalAction,
+    comment?: string,
+  ) => void;
+  readonly submittingApprovalIds?: ReadonlySet<string>;
+  readonly filePathCtx: FilePathContextValue;
+  readonly sandboxCtx: SandboxContextValue;
+}
+
+// ---------------------------------------------------------------------------
+// Scrollbar classes shared with the non-virtualized path
+// ---------------------------------------------------------------------------
+
+const SCROLLBAR_CLASSES = cn(
+  "[scrollbar-width:thin] [scrollbar-color:var(--color-border)_transparent]",
+  "[&::-webkit-scrollbar]:w-1.5",
+  "[&::-webkit-scrollbar-track]:bg-transparent",
+  "[&::-webkit-scrollbar-thumb]:rounded-full [&::-webkit-scrollbar-thumb]:bg-border/40",
+);
+
+// ---------------------------------------------------------------------------
+// Custom Virtuoso components
+// ---------------------------------------------------------------------------
+
+const ScrollerWithA11y = forwardRef<
+  HTMLDivElement,
+  ComponentPropsWithRef<"div">
+>(function ScrollerWithA11y(props, ref) {
+  return (
+    <div
+      {...props}
+      ref={ref}
+      role="log"
+      aria-live="polite"
+      aria-relevant="additions"
+      className={cn(props.className, SCROLLBAR_CLASSES)}
+    />
+  );
+});
+
+// ---------------------------------------------------------------------------
+// VirtualizedThread
+// ---------------------------------------------------------------------------
+
+const NEAR_BOTTOM_THRESHOLD_PX = 80;
+
+/**
+ * Internal component that renders a `MessageThread` item list via
+ * `react-virtuoso`. Handles bottom-anchored chat layout,
+ * follow-output scroll behavior, and the "Jump to latest" button.
+ *
+ * Not part of the public API — used only when `MessageThread` receives
+ * `virtualized={true}`.
+ *
+ * @internal
+ */
+export function VirtualizedThread({
+  items,
+  formatToolCallSummary,
+  onApprovalSubmit,
+  submittingApprovalIds,
+  filePathCtx,
+  sandboxCtx,
+}: VirtualizedThreadProps) {
+  const virtuosoRef = useRef<VirtuosoHandle>(null);
+  const scrollerRef = useRef<HTMLDivElement | null>(null);
+  const [isAtBottom, setIsAtBottom] = useState(true);
+
+  useDomNodeCount(scrollerRef, "MessageThread:virtualized");
+
+  const handleFollowOutput = useCallback(
+    (atBottom: boolean) => (atBottom ? "smooth" : false),
+    [],
+  );
+
+  const handleScrollerRef = useCallback((ref: HTMLElement | Window | null) => {
+    scrollerRef.current = ref instanceof HTMLDivElement ? ref : null;
+  }, []);
+
+  const jumpToLatest = useCallback(() => {
+    virtuosoRef.current?.scrollToIndex({
+      index: "LAST",
+      behavior: "smooth",
+    });
+  }, []);
+
+  const renderProps = useMemo(
+    () => ({
+      formatToolCallSummary,
+      onApprovalSubmit,
+      submittingApprovalIds,
+    }),
+    [formatToolCallSummary, onApprovalSubmit, submittingApprovalIds],
+  );
+
+  return (
+    <>
+      <SandboxContext.Provider value={sandboxCtx}>
+      <FilePathContext.Provider value={filePathCtx}>
+      <DevProfiler id="MessageThread:virtualized">
+        <Virtuoso
+          ref={virtuosoRef}
+          data={items as ThreadItem[]}
+          alignToBottom
+          followOutput={handleFollowOutput}
+          atBottomStateChange={setIsAtBottom}
+          atBottomThreshold={NEAR_BOTTOM_THRESHOLD_PX}
+          computeItemKey={(_index, item) => item.key}
+          increaseViewportBy={{ top: 200, bottom: 200 }}
+          scrollerRef={handleScrollerRef}
+          className="h-full"
+          components={{ Scroller: ScrollerWithA11y }}
+          itemContent={(index, item) => (
+            <div className="pb-4 pt-0 first:pt-6">
+              <ThreadItemWrapper animate={index >= items.length - 2}>
+                <ThreadItemRenderer
+                  item={item}
+                  {...renderProps}
+                />
+              </ThreadItemWrapper>
+            </div>
+          )}
+        />
+      </DevProfiler>
+      </FilePathContext.Provider>
+      </SandboxContext.Provider>
+      <JumpToLatestButton onClick={jumpToLatest} visible={!isAtBottom} />
+    </>
+  );
+}