@stigmer/react 0.3.4 → 0.4.1

package/src/billing/useCreateBillingPortalSession.ts

@@ -0,0 +1,76 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Return value of {@link useCreateBillingPortalSession}. */
+export interface UseCreateBillingPortalSessionReturn {
+  /**
+   * Open the Stripe Customer Portal for payment method management.
+   *
+   * On success, redirects the user to the Stripe-hosted portal page.
+   * The promise resolves before the redirect occurs.
+   */
+  readonly openPortal: (orgId: string) => Promise<void>;
+  /** `true` while the portal session is being created. */
+  readonly isLoading: boolean;
+  /** Error from the last failed attempt, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that opens the Stripe Customer Portal for payment
+ * method management.
+ *
+ * Wraps `billing.createBillingPortalSession` with loading and error
+ * state management. On success, redirects the user to the Stripe-hosted
+ * portal. Payment method changes are synced back via webhooks.
+ *
+ * @example
+ * ```tsx
+ * const { openPortal, isLoading } = useCreateBillingPortalSession();
+ *
+ * <button onClick={() => openPortal(orgId)} disabled={isLoading}>
+ *   Manage payment methods
+ * </button>
+ * ```
+ */
+export function useCreateBillingPortalSession(): UseCreateBillingPortalSessionReturn {
+  const stigmer = useStigmer();
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const openPortal = useCallback(
+    async (orgId: string): Promise<void> => {
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        const returnUrl =
+          typeof window !== "undefined" ? window.location.href : "";
+
+        const response = await stigmer.billing.createBillingPortalSession({
+          orgId,
+          returnUrl,
+        });
+
+        if (response.portalUrl) {
+          window.location.href = response.portalUrl;
+        }
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { openPortal, isLoading, error, clearError };
+}

package/src/billing/useCreateCheckoutSession.ts

@@ -0,0 +1,101 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { CreateCreditCheckoutSessionResponse } from "@stigmer/protos/ai/stigmer/billing/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Parameters for {@link useCreateCheckoutSession}'s `createSession` callback. */
+export interface CreateCheckoutSessionInput {
+  /** Organization purchasing credits. */
+  readonly orgId: string;
+  /** Credit pack to purchase (e.g., "starter", "growth", "team"). */
+  readonly packId: string;
+  /** URL to redirect to after successful payment. */
+  readonly successUrl: string;
+  /** URL to redirect to if the user cancels checkout. */
+  readonly cancelUrl: string;
+}
+
+/** Return value of {@link useCreateCheckoutSession}. */
+export interface UseCreateCheckoutSessionReturn {
+  /**
+   * Create a Stripe Checkout Session and redirect the user.
+   *
+   * On success, sets `window.location.href` to the Stripe-hosted
+   * checkout page URL. The promise resolves with the response before
+   * the redirect occurs, allowing callers to perform cleanup if needed.
+   */
+  readonly createSession: (
+    input: CreateCheckoutSessionInput,
+  ) => Promise<CreateCreditCheckoutSessionResponse>;
+  /** `true` while the checkout session is being created. */
+  readonly isSubmitting: boolean;
+  /** Error from the last failed attempt, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that creates a Stripe Checkout Session for credit
+ * pack purchases.
+ *
+ * Wraps `billing.createCreditCheckoutSession` with loading and error
+ * state management. On success, redirects the user to the Stripe-hosted
+ * checkout page. Credits are provisioned asynchronously via webhook
+ * after payment succeeds.
+ *
+ * @example
+ * ```tsx
+ * const { createSession, isSubmitting, error } = useCreateCheckoutSession();
+ *
+ * const handleBuy = () => {
+ *   createSession({
+ *     orgId,
+ *     packId: "growth",
+ *     successUrl: `${window.location.origin}/settings/billing?checkout=success`,
+ *     cancelUrl: `${window.location.origin}/settings/billing`,
+ *   });
+ * };
+ * ```
+ */
+export function useCreateCheckoutSession(): UseCreateCheckoutSessionReturn {
+  const stigmer = useStigmer();
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const createSession = useCallback(
+    async (
+      input: CreateCheckoutSessionInput,
+    ): Promise<CreateCreditCheckoutSessionResponse> => {
+      setIsSubmitting(true);
+      setError(null);
+
+      try {
+        const response = await stigmer.billing.createCreditCheckoutSession({
+          orgId: input.orgId,
+          packId: input.packId,
+          successUrl: input.successUrl,
+          cancelUrl: input.cancelUrl,
+        });
+
+        if (response.checkoutUrl) {
+          window.location.href = response.checkoutUrl;
+        }
+
+        return response;
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { createSession, isSubmitting, error, clearError };
+}

package/src/billing/useCreditLedger.ts

@@ -0,0 +1,79 @@
+"use client";
+
+import type {
+  CreditLedgerResponse,
+} from "@stigmer/protos/ai/stigmer/billing/v1/io_pb";
+import type { LedgerEntryType } from "@stigmer/protos/ai/stigmer/billing/v1/enum_pb";
+import { useStigmer } from "../hooks";
+import { useFetch } from "../internal/useFetch";
+
+/** Return value of {@link useCreditLedger}. */
+export interface UseCreditLedgerReturn {
+  /** The ledger response, or `null` before the first successful fetch. */
+  readonly ledger: CreditLedgerResponse | null;
+  /** `true` while the initial fetch is in flight. */
+  readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch from the server. */
+  readonly refetch: () => void;
+}
+
+/** Options for {@link useCreditLedger}. */
+export interface UseCreditLedgerOptions {
+  /** 1-based page number. Defaults to 1. */
+  readonly pageNum?: number;
+  /** Page size. Defaults to 20. */
+  readonly pageSize?: number;
+  /** Filter to specific ledger entry types. Empty means all types. */
+  readonly typeFilter?: LedgerEntryType[];
+}
+
+/**
+ * Data hook that fetches paginated credit ledger entries for an organization.
+ *
+ * Calls `billing.getCreditLedger` with optional pagination and type
+ * filtering. Returns the entries and total page count for building
+ * pagination controls.
+ *
+ * Pass `null` as `orgId` to skip fetching (stable no-op).
+ *
+ * @param orgId - Organization ID, or `null` to skip.
+ * @param options - Pagination and filter options.
+ *
+ * @example
+ * ```tsx
+ * const { ledger, isLoading } = useCreditLedger(orgId, { pageNum: 1 });
+ *
+ * if (isLoading) return <Skeleton />;
+ * if (!ledger) return null;
+ *
+ * return ledger.entries.map(entry => <LedgerRow key={entry.entryId} entry={entry} />);
+ * ```
+ */
+export function useCreditLedger(
+  orgId: string | null,
+  options: UseCreditLedgerOptions = {},
+): UseCreditLedgerReturn {
+  const stigmer = useStigmer();
+  const { pageNum = 1, pageSize = 20, typeFilter } = options;
+
+  const typeFilterKey = typeFilter?.join(",") ?? "";
+
+  const { data: ledger, isLoading, isRefetching, error, refetch } = useFetch(
+    orgId
+      ? () =>
+          stigmer.billing.getCreditLedger({
+            orgId,
+            page: { num: pageNum, size: pageSize },
+            typeFilter,
+          })
+      : null,
+    [orgId, pageNum, pageSize, typeFilterKey, stigmer],
+    null as CreditLedgerResponse | null,
+  );
+
+  return { ledger, isLoading, isRefetching, error, refetch };
+}

package/src/billing/useCustomerModelPricing.ts

@@ -0,0 +1,67 @@
+"use client";
+
+import type {
+  CustomerModelPricingResponse,
+} from "@stigmer/protos/ai/stigmer/billing/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { useFetch } from "../internal/useFetch";
+
+/** Return value of {@link useCustomerModelPricing}. */
+export interface UseCustomerModelPricingReturn {
+  /** The pricing response, or `null` before the first successful fetch. */
+  readonly pricing: CustomerModelPricingResponse | null;
+  /** `true` while the initial fetch is in flight. */
+  readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches the customer-facing model price list.
+ *
+ * Returns per-million-token prices for all billable models with
+ * billing policy markup already applied, organized by harness
+ * and cost tier.
+ *
+ * Pass `null` as `orgId` to skip fetching (stable no-op).
+ * Pass `undefined` to fetch default pricing (no org override).
+ *
+ * @param orgId - Organization ID for org-specific overrides,
+ *   `undefined` for default pricing, or `null` to skip.
+ *
+ * @example
+ * ```tsx
+ * const { pricing, isLoading } = useCustomerModelPricing(orgId);
+ *
+ * if (isLoading) return <Skeleton />;
+ * if (!pricing) return null;
+ *
+ * return pricing.entries.map(entry => (
+ *   <PricingRow key={entry.modelId} entry={entry} />
+ * ));
+ * ```
+ */
+export function useCustomerModelPricing(
+  orgId: string | undefined | null,
+): UseCustomerModelPricingReturn {
+  const stigmer = useStigmer();
+
+  const skip = orgId === null;
+
+  const { data: pricing, isLoading, isRefetching, error, refetch } = useFetch(
+    skip
+      ? null
+      : () =>
+          stigmer.billing.getCustomerModelPricing(
+            orgId ? { orgId } : undefined,
+          ),
+    [orgId, stigmer],
+    null as CustomerModelPricingResponse | null,
+  );
+
+  return { pricing, isLoading, isRefetching, error, refetch };
+}

package/src/billing/useSetAutoRechargeConfig.ts

@@ -0,0 +1,90 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+import type { BillingAccount } from "@stigmer/protos/ai/stigmer/billing/v1/billing_account_pb";
+
+/** Input for {@link useSetAutoRechargeConfig}. */
+export interface SetAutoRechargeConfigInput {
+  /** Organization ID to configure auto-recharge for. */
+  readonly orgId: string;
+  /** Whether auto-recharge is enabled. */
+  readonly enabled: boolean;
+  /** Trigger threshold in micro-USD. */
+  readonly thresholdMicros: bigint;
+  /** Fixed charge per recharge event in micro-USD. */
+  readonly rechargeAmountMicros: bigint;
+  /** Maximum monthly auto-recharge spend in micro-USD. */
+  readonly monthlyCapMicros: bigint;
+}
+
+/** Return value of {@link useSetAutoRechargeConfig}. */
+export interface UseSetAutoRechargeConfigReturn {
+  /**
+   * Save auto-recharge configuration. Returns the updated BillingAccount
+   * on success.
+   */
+  readonly setConfig: (input: SetAutoRechargeConfigInput) => Promise<BillingAccount>;
+  /** `true` while the configuration is being saved. */
+  readonly isSubmitting: boolean;
+  /** Error from the last failed attempt, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook for configuring auto-recharge settings.
+ *
+ * Wraps `billing.setAutoRechargeConfig` with loading and error state
+ * management. Returns the updated `BillingAccount` on success so the
+ * parent can refresh its cached data.
+ *
+ * @example
+ * ```tsx
+ * const { setConfig, isSubmitting, error } = useSetAutoRechargeConfig();
+ *
+ * await setConfig({
+ *   orgId,
+ *   enabled: true,
+ *   thresholdMicros: BigInt(5_000_000),
+ *   rechargeAmountMicros: BigInt(50_000_000),
+ *   monthlyCapMicros: BigInt(200_000_000),
+ * });
+ * ```
+ */
+export function useSetAutoRechargeConfig(): UseSetAutoRechargeConfigReturn {
+  const stigmer = useStigmer();
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const setConfig = useCallback(
+    async (input: SetAutoRechargeConfigInput): Promise<BillingAccount> => {
+      setIsSubmitting(true);
+      setError(null);
+
+      try {
+        const account = await stigmer.billing.setAutoRechargeConfig({
+          orgId: input.orgId,
+          enabled: input.enabled,
+          thresholdMicros: input.thresholdMicros,
+          rechargeAmountMicros: input.rechargeAmountMicros,
+          monthlyCapMicros: input.monthlyCapMicros,
+        });
+
+        return account;
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { setConfig, isSubmitting, error, clearError };
+}

package/src/composer/ComposerToolbar.tsx

@@ -97,7 +97,7 @@ export function ComposerToolbar({
   const hasTier2 = configureItems.length > 0;
   const showHarnessSeparate = showHarnessSelector && !showModelSelector;
   const hasExecParams = showHarnessSeparate || showModelSelector;
-  const harnessLocked = harness !== undefined && !showHarnessSelector;
+  const harnessLocked = harness !== undefined;
 
   return (
     <div className="flex items-center justify-between gap-2 border-t border-border-muted px-3 py-2">

package/src/composer/SessionComposer.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useEffect, useMemo, useRef, useState, type DragEvent, type KeyboardEvent } from "react";
+import { memo, useCallback, useEffect, useMemo, useRef, useState, type DragEvent, type KeyboardEvent } from "react";
 import { cn } from "@stigmer/theme";
 import { getUserMessage, type AttachmentInput, type EnvVarInput, type McpServerUsageInput, type ResourceRef } from "@stigmer/sdk";
 import { useComposer } from "./useComposer";
@@ -33,6 +33,7 @@ import {
   SYSTEM_ENV_VAR_KEYS,
   resolveSystemEnvVarValues,
 } from "../environment/systemEnvVars";
+import { useRenderTracer } from "../internal/dev";
 import { RunnerPhase } from "@stigmer/protos/ai/stigmer/agentic/runner/v1/enum_pb";
 import {
   isActivePhase,
@@ -371,7 +372,7 @@ export interface SessionComposerProps {
  * />
  * ```
  */
-export function SessionComposer({
+export const SessionComposer = memo(function SessionComposer({
   onSubmit,
   isSubmitting = false,
   disabled = false,
@@ -407,7 +408,24 @@ export function SessionComposer({
   ariaLabel = "Send message",
   className,
 }: SessionComposerProps) {
-  const [modelId, setModelId] = useState<string | undefined>(defaultModelId);
+  useRenderTracer("SessionComposer", { disabled, isSubmitting });
+
+  const [modelId, setModelIdRaw] = useState<string | undefined>(defaultModelId);
+  const userOverrodeModel = useRef(false);
+
+  // Sync internal modelId when the external defaultModelId prop changes
+  // (e.g., lastExecModelId resolves after executions load). Only sync if the
+  // user hasn't made a local selection in this composer instance.
+  useEffect(() => {
+    if (!userOverrodeModel.current && defaultModelId !== undefined) {
+      setModelIdRaw(defaultModelId);
+    }
+  }, [defaultModelId]);
+
+  const setModelId = useCallback((id: string | undefined) => {
+    userOverrodeModel.current = true;
+    setModelIdRaw(id);
+  }, []);
 
   const [displayNames, setDisplayNames] = useState<Map<string, string>>(
     () => new Map(),
@@ -1418,7 +1436,7 @@ export function SessionComposer({
       </div>
     </div>
   );
-}
+});
 
 // ---------------------------------------------------------------------------
 // Agent setup error — secret-flow guidance or generic fallback

package/src/composer/__tests__/SessionComposer-memo.test.ts

@@ -0,0 +1,26 @@
+import { describe, it, expect } from "vitest";
+import { SessionComposer } from "../SessionComposer";
+
+describe("SessionComposer — memo isolation", () => {
+  it("is wrapped in React.memo (shallow prop comparison)", () => {
+    // React.memo returns an exotic component with $$typeof set to
+    // Symbol.for("react.memo") and a `type` field pointing at the
+    // inner function. Regular function components have neither.
+    const memoSymbol = Symbol.for("react.memo");
+    const typed = SessionComposer as unknown as { $$typeof: symbol; type: Function; compare: unknown };
+
+    expect(typed.$$typeof).toBe(memoSymbol);
+    expect(typeof typed.type).toBe("function");
+    // The transform may rename the inner function to avoid shadowing
+    // the outer `const SessionComposer` binding (e.g. "SessionComposer2").
+    expect(typed.type.name).toMatch(/^SessionComposer/);
+  });
+
+  it("uses default shallow comparison (no custom areEqual)", () => {
+    const typed = SessionComposer as unknown as { compare: unknown };
+
+    // When React.memo is called without a second argument, `compare`
+    // is null — React falls back to shallow prop comparison.
+    expect(typed.compare).toBeNull();
+  });
+});

package/src/execution/ApprovalCard.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { memo, useCallback, useEffect, useMemo, useState } from "react";
 import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
 import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { cn } from "@stigmer/theme";
@@ -39,6 +39,10 @@ export interface ApprovalCardProps {
  * dispatch, ensuring pixel-level parity between the approval
  * preview and the post-execution detail view.
  *
+ * Wrapped in `React.memo` — structural sharing (T04) preserves the
+ * `PendingApproval` reference when unchanged, so approval cards
+ * skip re-renders during unrelated stream updates.
+ *
  * @example
  * ```tsx
  * <ApprovalCard
@@ -48,7 +52,7 @@ export interface ApprovalCardProps {
  * />
  * ```
  */
-export function ApprovalCard({
+export const ApprovalCard = memo(function ApprovalCard({
   pendingApproval,
   onSubmit,
   isSubmitting = false,
@@ -198,7 +202,7 @@ export function ApprovalCard({
       </div>
     </div>
   );
-}
+});
 
 // ---------------------------------------------------------------------------
 // Internal sub-components

package/src/execution/ExecutionPhaseBadge.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { memo } from "react";
 import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { cn } from "@stigmer/theme";
 
@@ -97,7 +98,7 @@ const PHASE_CONFIG: ReadonlyMap<ExecutionPhase, PhaseConfig> = new Map([
  * <ExecutionPhaseBadge phase={ExecutionPhase.EXECUTION_COMPLETED} />
  * ```
  */
-export function ExecutionPhaseBadge({
+export const ExecutionPhaseBadge = memo(function ExecutionPhaseBadge({
   phase,
   className,
 }: ExecutionPhaseBadgeProps) {
@@ -122,7 +123,7 @@ export function ExecutionPhaseBadge({
       {config.label}
     </span>
   );
-}
+});
 
 function DotIcon() {
   return (

package/src/execution/MessageEntry.tsx

@@ -1,11 +1,12 @@
 "use client";
 
-import { useState } from "react";
-import Markdown from "react-markdown";
+import { memo, useState } from "react";
+import { Streamdown } from "streamdown";
 import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import { MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { cn } from "@stigmer/theme";
-import { MARKDOWN_COMPONENTS, REMARK_PLUGINS } from "../internal/markdown-components";
+import { MARKDOWN_COMPONENTS } from "../internal/markdown-components";
+import { useRenderTracer } from "../internal/dev";
 
 /** Props for {@link MessageEntry}. */
 export interface MessageEntryProps {
@@ -19,14 +20,18 @@ export interface MessageEntryProps {
  * Renders a single message in the conversation thread.
  *
  * - `MESSAGE_HUMAN` — plain text with muted background
- * - `MESSAGE_AI` — markdown-rendered via `react-markdown` + `remark-gfm`,
- *   with a blinking cursor while streaming
+ * - `MESSAGE_AI` — markdown-rendered via Streamdown with block-level
+ *   memoization and streaming-aware incomplete-syntax healing
  * - `MESSAGE_THINKING` — collapsible thinking block with subdued styling,
  *   collapsed by default showing a brief summary
  * - `MESSAGE_SYSTEM` — small muted text
  * - `MESSAGE_TOOL` / `UNSPECIFIED` — renders nothing (tool results are
  *   consumed by {@link ToolCallGroup})
  *
+ * Wrapped in `React.memo` — structural sharing (T04) guarantees that
+ * unchanged messages keep the same object reference, so completed
+ * messages skip re-renders entirely during streaming.
+ *
  * Purely presentational — no data fetching, no state.
  * All visual properties flow through `--stgm-*` tokens.
  *
@@ -35,7 +40,16 @@ export interface MessageEntryProps {
  * <MessageEntry message={agentMessage} />
  * ```
  */
-export function MessageEntry({ message, className }: MessageEntryProps) {
+export const MessageEntry = memo(function MessageEntry({
+  message,
+  className,
+}: MessageEntryProps) {
+  useRenderTracer("MessageEntry", {
+    messageType: message.type,
+    contentLength: message.content.length,
+    isStreaming: message.isStreaming,
+  });
+
   switch (message.type) {
     case MessageType.MESSAGE_HUMAN:
       return <HumanMessage content={message.content} className={className} />;
@@ -60,7 +74,7 @@ export function MessageEntry({ message, className }: MessageEntryProps) {
     default:
       return null;
   }
-}
+});
 
 function HumanMessage({
   content,
@@ -89,6 +103,8 @@ function AiMessage({
   isStreaming: boolean;
   className?: string;
 }) {
+  useRenderTracer("AiMessage", { contentLength: content.length, isStreaming });
+
   return (
     <div
       role="article"
@@ -97,18 +113,13 @@ function AiMessage({
       className={cn("px-4 py-3", className)}
     >
       <div className="stgm-prose">
-        <Markdown
-          remarkPlugins={REMARK_PLUGINS}
+        <Streamdown
           components={MARKDOWN_COMPONENTS}
+          isAnimating={isStreaming}
+          caret="block"
         >
           {content}
-        </Markdown>
-        {isStreaming && (
-          <span
-            className="inline-block w-[2px] h-[1em] bg-foreground align-text-bottom animate-pulse ml-0.5"
-            aria-hidden="true"
-          />
-        )}
+        </Streamdown>
       </div>
     </div>
   );