@crediball/react 0.3.6 → 0.4.0

package/dist/PaywallModal.js

@@ -1,37 +1,46 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
-import { tokens } from "./theme";
+import { useEffect, useRef, useState } from "react";
+import { theme, accentStyle } from "./theme";
+import { formatCredits, formatMoney } from "./format";
+/** Shared uppercase eyebrow-label style used above the subscribe/buy-credits sections. */
+function sectionLabelStyle(marginBottom) {
+    return {
+        fontSize: 11,
+        fontWeight: 600,
+        letterSpacing: "0.06em",
+        textTransform: "uppercase",
+        color: theme.inkMuted,
+        marginBottom,
+    };
+}
 /**
  * Pattern B — Paywall moment. Render when a user has insufficient credits to
- * continue. The host controls when it appears; no Crediball branding.
+ * continue. The host controls when it appears; shows a small "Powered by
+ * Crediball" line by default (set `hideBranding` to remove it).
  */
-function fmtCredits(n) {
-    return new Intl.NumberFormat().format(Math.round(n));
-}
-function fmtMoney(n, currency) {
-    try {
-        return new Intl.NumberFormat(undefined, { style: "currency", currency }).format(n);
-    }
-    catch {
-        return `${n.toFixed(2)} ${currency}`;
-    }
-}
-export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlans, onSelectPlan, activeSubscription, onCancelSubscription, amounts = [5, 10], amountPrefix = "Add €", title = "You need more credits to continue.", description = "Top up to keep using this feature.", onAdd, onClose, allowCustom = false, customMin = 1, customMax, currencySymbol = "€", balance, balanceRate, currency = "EUR", accentColor = tokens.primary, style, }) {
-    // Stack the top-up buttons one-per-line on narrow (mobile) screens.
+export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlans, onSelectPlan, activeSubscription, onCancelSubscription, amounts = [5, 10], amountPrefix = "Add €", title = "You need more credits to continue.", description = "Top up to keep using this feature.", onAdd, onClose, allowCustom = false, addButtonText = "Add", customMin = 1, customMax, currencySymbol = "€", balance, balanceRate, currency = "EUR", usage, usageLabel = "Usage", hideBranding = false, accentColor, style, }) {
+    // Stack the top-up buttons one-per-line when the dialog itself is narrow.
+    // Measured off the dialog's own box (via ResizeObserver) rather than the
+    // window — in normal use the two are the same width, but this also makes
+    // the layout correctly respond when the dialog is rendered inside a
+    // narrower container (e.g. a device-mockup preview) on a wide screen.
     const [narrow, setNarrow] = useState(false);
+    const overlayRef = useRef(null);
     const [customValue, setCustomValue] = useState("");
     const [customError, setCustomError] = useState(null);
     const [cancelPending, setCancelPending] = useState(false);
     const [cancelDone, setCancelDone] = useState(false);
     useEffect(() => {
-        if (typeof window === "undefined" || !window.matchMedia)
+        const el = overlayRef.current;
+        if (!el || typeof ResizeObserver === "undefined")
             return;
-        const mq = window.matchMedia("(max-width: 480px)");
-        const update = () => setNarrow(mq.matches);
-        update();
-        mq.addEventListener("change", update);
-        return () => mq.removeEventListener("change", update);
+        const observer = new ResizeObserver((entries) => {
+            const width = entries[0]?.contentRect.width ?? el.clientWidth;
+            setNarrow(width <= 480);
+        });
+        observer.observe(el);
+        return () => observer.disconnect();
     }, []);
     if (!open)
         return null;
@@ -69,14 +78,16 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
         appearance: "none",
         border: "none",
         cursor: "pointer",
-        background: accentColor,
-        color: tokens.onPrimary,
-        fontFamily: tokens.fontStack,
-        fontSize: 17,
-        padding: "11px 22px",
-        borderRadius: tokens.radiusPill,
+        background: theme.accent,
+        color: theme.onAccent,
+        fontFamily: theme.font,
+        fontWeight: 500,
+        fontSize: 14,
+        lineHeight: "24px",
+        padding: "8px 16px",
+        borderRadius: theme.radiusPill,
     };
-    return (_jsx("div", { role: "dialog", "aria-modal": "true", style: {
+    return (_jsx("div", { ref: overlayRef, role: "dialog", "aria-modal": "true", style: {
             position: "fixed",
             inset: 0,
             zIndex: 2147483647,
@@ -84,37 +95,42 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
             alignItems: "center",
             justifyContent: "center",
             padding: 24,
-            background: tokens.overlay,
-            fontFamily: tokens.fontStack,
+            background: theme.overlay,
+            fontFamily: theme.font,
+            // Mobile Safari/Chrome auto-inflate font sizes in narrow columns for
+            // readability, which throws off this dialog's fixed layout (extra
+            // text wrapping eats the padding around it). Opt out — sizes here
+            // are already chosen deliberately.
+            WebkitTextSizeAdjust: "100%",
+            textSizeAdjust: "100%",
+            ...accentStyle(accentColor),
         }, onClick: onClose, children: _jsxs("div", { onClick: (e) => e.stopPropagation(), style: {
                 width: "100%",
                 maxWidth: 420,
                 padding: 32,
-                borderRadius: tokens.radiusCard,
-                background: tokens.canvas,
+                borderRadius: theme.radiusCard,
+                background: theme.canvas,
+                boxShadow: "0px 4px 6px 0px rgba(0, 0, 0, 0.09)",
                 ...style,
             }, children: [balance != null && (_jsxs("div", { style: {
-                        marginBottom: 24,
-                        paddingBottom: 20,
-                        borderBottom: `1px solid ${tokens.hairline}`,
-                    }, children: [_jsx("div", { style: {
-                                fontSize: 11,
-                                fontWeight: 600,
-                                letterSpacing: "0.06em",
-                                textTransform: "uppercase",
-                                color: tokens.inkMuted,
-                                marginBottom: 4,
-                            }, children: "Your balance" }), _jsxs("div", { style: { display: "flex", alignItems: "baseline", gap: 8, flexWrap: "wrap" }, children: [_jsxs("span", { style: { fontSize: 22, fontWeight: 600, color: tokens.ink }, children: [fmtCredits(balance), " credits"] }), balanceRate && balanceRate > 0 ? (_jsxs("span", { style: { fontSize: 13, color: tokens.inkMuted }, children: ["\u2248 ", fmtMoney(balance / balanceRate, currency)] })) : null] })] })), _jsx("h3", { style: { margin: 0, fontSize: 24, fontWeight: 600, color: tokens.ink, letterSpacing: "-0.01em" }, children: activeSubscription
+                        display: "flex",
+                        gap: 16,
+                        marginBottom: 16,
+                        paddingBottom: 16,
+                        borderBottom: `1px solid ${theme.hairline}`,
+                    }, children: [_jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 2 }, children: [_jsx("span", { style: { fontSize: 11, color: theme.inkMuted }, children: "Balance" }), _jsxs("span", { style: { fontSize: 12, fontWeight: 500, color: theme.ink }, children: [formatCredits(balance), balanceRate && balanceRate > 0
+                                            ? ` (≈${formatMoney(balance / balanceRate, currency)})`
+                                            : ""] })] }), usage != null ? (_jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 2 }, children: [_jsx("span", { style: { fontSize: 11, color: theme.inkMuted }, children: usageLabel }), _jsxs("span", { style: { fontSize: 12, fontWeight: 500, color: theme.ink }, children: [formatCredits(usage), " credits"] })] })) : null] })), _jsx("h3", { style: { margin: 0, fontSize: 18, fontWeight: 600, lineHeight: "28px", color: theme.ink }, children: activeSubscription
                         ? "You've used all your credits for this period."
-                        : title }), _jsx("p", { style: { marginTop: 8, marginBottom: 0, fontSize: 14, color: tokens.inkMuted }, children: activeSubscription
+                        : title }), _jsx("p", { style: { marginTop: 8, marginBottom: 0, fontSize: 13, color: theme.inkMuted }, children: activeSubscription
                         ? `Your ${activeSubscription.planName} credits renew on ${new Date(activeSubscription.currentPeriodEnd).toLocaleDateString()}.`
                         : description }), activeSubscription && (_jsxs("div", { style: {
                         marginTop: 16,
                         padding: "12px 16px",
-                        borderRadius: tokens.radiusCard,
+                        borderRadius: theme.radiusCard,
                         background: "#f5f5f7",
-                        border: `1px solid ${tokens.hairline}`,
-                    }, children: [_jsx("div", { style: { fontSize: 13, fontWeight: 600, color: tokens.ink }, children: cancelDone ? "Subscription canceled" : `${activeSubscription.planName} · ${activeSubscription.planPeriod}` }), !cancelDone && (_jsx("button", { onClick: handleCancelSubscription, disabled: cancelPending, style: {
+                        border: `1px solid ${theme.hairline}`,
+                    }, children: [_jsx("div", { style: { fontSize: 13, fontWeight: 600, color: theme.ink }, children: cancelDone ? "Subscription canceled" : `${activeSubscription.planName} · ${activeSubscription.planPeriod}` }), !cancelDone && (_jsx("button", { onClick: handleCancelSubscription, disabled: cancelPending, style: {
                                 marginTop: 8,
                                 appearance: "none",
                                 border: "none",
@@ -122,61 +138,41 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
                                 cursor: cancelPending ? "default" : "pointer",
                                 padding: 0,
                                 fontSize: 13,
-                                color: tokens.inkMuted,
-                                fontFamily: tokens.fontStack,
+                                color: theme.inkMuted,
+                                fontFamily: theme.font,
                                 textDecoration: "underline",
-                            }, children: cancelPending ? "Canceling…" : "Cancel subscription" }))] })), !activeSubscription && subscriptionPlans && subscriptionPlans.length > 0 && (_jsxs("div", { style: { marginTop: 24 }, children: [_jsx("div", { style: {
-                                fontSize: 11,
-                                fontWeight: 600,
-                                letterSpacing: "0.06em",
-                                textTransform: "uppercase",
-                                color: tokens.inkMuted,
-                                marginBottom: 8,
-                            }, children: "Subscribe" }), _jsx("div", { style: { display: "flex", flexDirection: "column", gap: 8 }, children: subscriptionPlans.map((plan) => (_jsxs("button", { onClick: () => onSelectPlan?.(plan), style: {
+                            }, children: cancelPending ? "Canceling…" : "Cancel subscription" }))] })), !activeSubscription && subscriptionPlans && subscriptionPlans.length > 0 && (_jsxs("div", { style: { marginTop: 24 }, children: [_jsx("div", { style: sectionLabelStyle(8), children: "Subscribe" }), _jsx("div", { style: { display: "flex", flexDirection: "column", gap: 8 }, children: subscriptionPlans.map((plan) => (_jsxs("button", { onClick: () => onSelectPlan?.(plan), style: {
                                     ...buttonStyle,
                                     flex: "none",
                                     display: "flex",
                                     justifyContent: "space-between",
                                     alignItems: "center",
-                                }, children: [_jsx("span", { children: plan.name }), _jsxs("span", { style: { opacity: 0.85, fontSize: 14 }, children: [fmtMoney(plan.price, currency), "/", plan.period === "monthly" ? "mo" : "yr", " \u00B7 ", fmtCredits(plan.credits), " cr"] })] }, plan.id))) })] })), _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 10, marginTop: 24 }, children: [(!activeSubscription && subscriptionPlans && subscriptionPlans.length > 0) && (_jsx("div", { style: {
-                                fontSize: 11,
-                                fontWeight: 600,
-                                letterSpacing: "0.06em",
-                                textTransform: "uppercase",
-                                color: tokens.inkMuted,
-                                marginBottom: -2,
-                            }, children: activeSubscription ? "Add extra credits" : "Or buy credits" })), activeSubscription && packages && packages.length > 0 && (_jsx("div", { style: {
-                                fontSize: 11,
-                                fontWeight: 600,
-                                letterSpacing: "0.06em",
-                                textTransform: "uppercase",
-                                color: tokens.inkMuted,
-                                marginBottom: -2,
-                            }, children: "Add extra credits" })), packages && packages.length > 0
-                            ? packages.map((pkg) => (_jsxs("button", { onClick: () => onSelectPackage?.(pkg), style: { ...buttonStyle, flex: "none", display: "flex", justifyContent: "space-between", alignItems: "center" }, children: [_jsx("span", { children: pkg.name }), _jsxs("span", { style: { opacity: 0.85, fontSize: 14 }, children: [fmtMoney(pkg.price, currency), " \u00B7 ", fmtCredits(pkg.credits), " cr"] })] }, pkg.id)))
-                            : (!activeSubscription && (_jsx("div", { style: { display: "flex", flexDirection: narrow ? "column" : "row", gap: 12 }, children: amounts.map((amount) => (_jsxs("button", { onClick: () => onAdd?.(amount), style: buttonStyle, children: [amountPrefix, amount] }, amount))) })))] }), allowCustom ? (_jsxs("div", { style: { marginTop: 12 }, children: [_jsxs("div", { style: { display: "flex", gap: 8, alignItems: "center" }, children: [_jsx("span", { style: { fontSize: 17, color: tokens.inkMuted }, children: currencySymbol }), _jsx("input", { value: customValue, onChange: (e) => setCustomValue(e.target.value), inputMode: "decimal", placeholder: String(customMin), style: {
+                                }, children: [_jsx("span", { children: plan.name }), _jsxs("span", { style: { opacity: 0.85, fontSize: 14 }, children: [formatMoney(plan.price, currency), "/", plan.period === "monthly" ? "mo" : "yr", " \u00B7 ", formatCredits(plan.credits), " cr"] })] }, plan.id))) })] })), _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 10, marginTop: 24 }, children: [(!activeSubscription && subscriptionPlans && subscriptionPlans.length > 0) && (_jsx("div", { style: sectionLabelStyle(-2), children: "Or buy credits" })), activeSubscription && packages && packages.length > 0 && (_jsx("div", { style: sectionLabelStyle(-2), children: "Add extra credits" })), packages && packages.length > 0
+                            ? packages.map((pkg) => (_jsxs("button", { onClick: () => onSelectPackage?.(pkg), style: { ...buttonStyle, flex: "none", display: "flex", justifyContent: "space-between", alignItems: "center" }, children: [_jsx("span", { children: pkg.name }), _jsxs("span", { style: { opacity: 0.85, fontSize: 14 }, children: [formatMoney(pkg.price, currency), " \u00B7 ", formatCredits(pkg.credits), " cr"] })] }, pkg.id)))
+                            : (!activeSubscription && (_jsx("div", { style: { display: "flex", flexDirection: narrow ? "column" : "row", gap: 12 }, children: amounts.map((amount) => (_jsxs("button", { onClick: () => onAdd?.(amount), style: buttonStyle, children: [amountPrefix, amount] }, amount))) })))] }), allowCustom ? (_jsxs("div", { style: { marginTop: 12 }, children: [_jsxs("div", { style: { display: "flex", gap: 8, alignItems: "center" }, children: [_jsx("span", { style: { fontSize: 14, color: theme.inkMuted }, children: currencySymbol }), _jsx("input", { value: customValue, onChange: (e) => setCustomValue(e.target.value), inputMode: "decimal", placeholder: String(customMin), style: {
                                         flex: 1,
                                         minWidth: 0,
                                         appearance: "none",
-                                        fontFamily: tokens.fontStack,
-                                        fontSize: 17,
-                                        padding: "11px 14px",
-                                        borderRadius: tokens.radiusPill,
-                                        border: `1px solid ${tokens.hairline}`,
-                                        color: tokens.ink,
-                                        background: tokens.canvas,
+                                        fontFamily: theme.font,
+                                        fontSize: 14,
+                                        lineHeight: "20px",
+                                        padding: "8px 12px",
+                                        borderRadius: theme.radiusPill,
+                                        border: `1px solid ${theme.hairline}`,
+                                        color: theme.ink,
+                                        background: theme.canvas,
                                         outline: "none",
-                                    } }), _jsx("button", { onClick: submitCustom, style: { ...buttonStyle, flex: "none" }, children: "Add" })] }), customError ? (_jsx("p", { style: { margin: "8px 0 0", fontSize: 13, color: accentColor }, children: customError })) : null] })) : null, onClose ? (_jsx("button", { onClick: onClose, style: {
+                                    } }), _jsx("button", { onClick: submitCustom, style: { ...buttonStyle, flex: "none" }, children: addButtonText })] }), customError ? (_jsx("p", { style: { margin: "8px 0 0", fontSize: 13, color: theme.accent }, children: customError })) : null] })) : null, onClose ? (_jsx("button", { onClick: onClose, style: {
                         width: "100%",
                         marginTop: 12,
                         appearance: "none",
                         border: "none",
                         cursor: "pointer",
                         background: "transparent",
-                        color: tokens.inkMuted,
-                        fontFamily: tokens.fontStack,
-                        fontSize: 14,
-                        padding: "11px 22px",
-                        borderRadius: tokens.radiusPill,
-                    }, children: "Not now" })) : null] }) }));
+                        color: theme.inkMuted,
+                        fontFamily: theme.font,
+                        fontSize: 12,
+                        padding: "8px 16px",
+                        borderRadius: theme.radiusPill,
+                    }, children: "Not now" })) : null, !hideBranding && (_jsx("div", { style: { display: "flex", justifyContent: "flex-end", marginTop: 10 }, children: _jsx("span", { style: { fontSize: 10, color: theme.inkMuted }, children: "Powered by Crediball." }) }))] }) }));
 }

package/dist/creditEvent.d.ts

@@ -1,21 +1,8 @@
 /**
- * Global custom-event bus for insufficient-credits signals.
- *
- * Any code — a useChat onError, an XHR error handler, a Redux middleware, a
- * server action catch block — can call notifyInsufficientCredits() and every
- * mounted CrediballProvider / usePaywall instance will open the paywall.
- *
- * This decouples the signal source from the UI, so the paywall works regardless
- * of how the HTTP request was made (fetch, XHR, EventSource, AI SDK internals…).
+ * Re-exported from @crediball/core so the event bus is shared between
+ * @crediball/react, @crediball/elements, and any core-based data client —
+ * a signal fired from one surface (e.g. the web-components layer) is seen by
+ * every other. Kept as a distinct module path for backwards compatibility
+ * with existing imports inside this package.
  */
-/**
- * Fire the global insufficient-credits signal. Safe to call from anywhere in
- * the app — server components excluded (DOM only). Every mounted paywall
- * component will react to it automatically.
- */
-export declare function notifyInsufficientCredits(): void;
-/**
- * Subscribe to the global insufficient-credits signal.
- * Returns an unsubscribe function for use in useEffect cleanup.
- */
-export declare function subscribeInsufficientCredits(listener: () => void): () => void;
+export { notifyInsufficientCredits, subscribeInsufficientCredits } from "@crediball/core";

package/dist/creditEvent.js

@@ -1,31 +1,8 @@
 /**
- * Global custom-event bus for insufficient-credits signals.
- *
- * Any code — a useChat onError, an XHR error handler, a Redux middleware, a
- * server action catch block — can call notifyInsufficientCredits() and every
- * mounted CrediballProvider / usePaywall instance will open the paywall.
- *
- * This decouples the signal source from the UI, so the paywall works regardless
- * of how the HTTP request was made (fetch, XHR, EventSource, AI SDK internals…).
+ * Re-exported from @crediball/core so the event bus is shared between
+ * @crediball/react, @crediball/elements, and any core-based data client —
+ * a signal fired from one surface (e.g. the web-components layer) is seen by
+ * every other. Kept as a distinct module path for backwards compatibility
+ * with existing imports inside this package.
  */
-const EVENT = "crediball:insufficient-credits";
-/**
- * Fire the global insufficient-credits signal. Safe to call from anywhere in
- * the app — server components excluded (DOM only). Every mounted paywall
- * component will react to it automatically.
- */
-export function notifyInsufficientCredits() {
-    if (typeof window === "undefined")
-        return;
-    window.dispatchEvent(new CustomEvent(EVENT));
-}
-/**
- * Subscribe to the global insufficient-credits signal.
- * Returns an unsubscribe function for use in useEffect cleanup.
- */
-export function subscribeInsufficientCredits(listener) {
-    if (typeof window === "undefined")
-        return () => { };
-    window.addEventListener(EVENT, listener);
-    return () => window.removeEventListener(EVENT, listener);
-}
+export { notifyInsufficientCredits, subscribeInsufficientCredits } from "@crediball/core";

package/dist/fetchWatcher.d.ts

@@ -1,18 +1,24 @@
 /**
- * Module-level singleton that patches window.fetch once and fans out to all
- * registered listeners (from CrediballProvider and/or usePaywall). Only one
- * fetch patch exists at a time regardless of how many components subscribe.
- * Reference-counted: the patch is removed when the last listener unsubscribes.
+ * Patches window.fetch at module-import time — before any React component
+ * mounts and before any AI SDK can capture the fetch reference. This is the
+ * key difference from installing the patch in a useEffect: by the time a
+ * useEffect runs, the Vercel AI SDK (and others) may have already resolved
+ * their fetch reference and bypass the patch entirely.
  *
- * Handles two credit-error surfaces:
- *   1. HTTP 402 — regular JSON responses (non-streaming routes).
- *   2. HTTP 200 text/event-stream or ndjson — streaming routes where the error
- *      arrives as a chunk in the stream body rather than an HTTP status code.
+ * Handles three credit-error surfaces:
+ *   1. HTTP 402 with { code: "insufficient_credits" } — regular JSON routes.
+ *   2. HTTP 200 streaming body containing "insufficient_credits" — SSE, ndjson,
+ *      or Vercel AI SDK data-stream (text/plain) routes.
+ *   3. Manual call to notifyInsufficientCredits() from any error handler.
  */
 type Listener = () => void;
 /**
  * Subscribe to insufficient-credits events detected in window.fetch.
- * Returns an unsubscribe function — call it in your useEffect cleanup.
+ * Returns an unsubscribe function for use in useEffect cleanup.
+ *
+ * The fetch patch is installed at module load time regardless of whether
+ * anyone calls this function. This exists for components that need a direct
+ * callback rather than the global DOM event.
  */
 export declare function subscribeFetchWatcher(listener: Listener): () => void;
 export {};

package/dist/fetchWatcher.js

@@ -1,25 +1,28 @@
 /**
- * Module-level singleton that patches window.fetch once and fans out to all
- * registered listeners (from CrediballProvider and/or usePaywall). Only one
- * fetch patch exists at a time regardless of how many components subscribe.
- * Reference-counted: the patch is removed when the last listener unsubscribes.
+ * Patches window.fetch at module-import time — before any React component
+ * mounts and before any AI SDK can capture the fetch reference. This is the
+ * key difference from installing the patch in a useEffect: by the time a
+ * useEffect runs, the Vercel AI SDK (and others) may have already resolved
+ * their fetch reference and bypass the patch entirely.
  *
- * Handles two credit-error surfaces:
- *   1. HTTP 402 — regular JSON responses (non-streaming routes).
- *   2. HTTP 200 text/event-stream or ndjson — streaming routes where the error
- *      arrives as a chunk in the stream body rather than an HTTP status code.
+ * Handles three credit-error surfaces:
+ *   1. HTTP 402 with { code: "insufficient_credits" } — regular JSON routes.
+ *   2. HTTP 200 streaming body containing "insufficient_credits" — SSE, ndjson,
+ *      or Vercel AI SDK data-stream (text/plain) routes.
+ *   3. Manual call to notifyInsufficientCredits() from any error handler.
  */
 import { notifyInsufficientCredits } from "./creditEvent";
-let _original = null;
 const _listeners = new Set();
 function fire() {
-    // Dispatch the global event so ALL mounted paywall instances react,
-    // plus any manual subscribeInsufficientCredits() listeners.
     notifyInsufficientCredits();
-    // Also call per-instance listeners registered via subscribeFetchWatcher
-    // (kept for backwards compatibility with direct watcher subscribers).
     _listeners.forEach((fn) => fn());
 }
+function isStreamingContentType(ct) {
+    return (ct.includes("text/event-stream") ||
+        ct.includes("ndjson") ||
+        // Vercel AI SDK uses text/plain for its data-stream protocol
+        ct.includes("text/plain"));
+}
 /**
  * Tee the streaming response body and scan each chunk for the
  * `insufficient_credits` signal. Returns a new Response whose body is the
@@ -54,10 +57,11 @@ function watchStream(res) {
         headers: res.headers,
     });
 }
-function install() {
-    if (typeof window === "undefined" || _original !== null)
-        return;
-    _original = window.fetch;
+// ── Install patch immediately at module load time ─────────────────────────
+// Running here (not in a useEffect) ensures the patch is in place before any
+// SDK or framework code captures the window.fetch reference.
+if (typeof window !== "undefined") {
+    const _original = window.fetch;
     window.fetch = async (...args) => {
         const res = await _original(...args);
         if (res.status === 402) {
@@ -72,43 +76,31 @@ function install() {
                 }
             })
                 .catch(() => {
-                // Non-JSON 402 — fire anyway; a 402 from the app's own API route is
-                // almost certainly a credit shortage. Set watchFetch=false and call
-                // trigger() manually if your app uses 402 for other purposes.
+                // Non-JSON 402 — fire anyway.
                 fire();
             });
             return res;
         }
-        // Watch streaming responses for embedded credit errors (HTTP 200 with
-        // text/event-stream or ndjson — the common AI streaming pattern).
         if (res.body) {
             const ct = res.headers.get("content-type") ?? "";
-            if (ct.includes("text/event-stream") || ct.includes("ndjson")) {
+            if (isStreamingContentType(ct)) {
                 return watchStream(res);
             }
         }
         return res;
     };
 }
-function uninstall() {
-    if (typeof window === "undefined" || _original === null)
-        return;
-    window.fetch = _original;
-    _original = null;
-}
 /**
  * Subscribe to insufficient-credits events detected in window.fetch.
- * Returns an unsubscribe function — call it in your useEffect cleanup.
+ * Returns an unsubscribe function for use in useEffect cleanup.
+ *
+ * The fetch patch is installed at module load time regardless of whether
+ * anyone calls this function. This exists for components that need a direct
+ * callback rather than the global DOM event.
  */
 export function subscribeFetchWatcher(listener) {
     if (typeof window === "undefined")
         return () => { };
-    if (_listeners.size === 0)
-        install();
     _listeners.add(listener);
-    return () => {
-        _listeners.delete(listener);
-        if (_listeners.size === 0)
-            uninstall();
-    };
+    return () => _listeners.delete(listener);
 }

package/dist/format.d.ts

@@ -0,0 +1,4 @@
+/** Formats a raw credit balance as a locale-formatted whole number (e.g. 840 → "840"). */
+export declare function formatCredits(credits: number): string;
+/** Formats a monetary amount in the given ISO 4217 currency, falling back to a plain number + code for unknown currencies. */
+export declare function formatMoney(amount: number, currency: string): string;

package/dist/format.js

@@ -0,0 +1,13 @@
+/** Formats a raw credit balance as a locale-formatted whole number (e.g. 840 → "840"). */
+export function formatCredits(credits) {
+    return new Intl.NumberFormat(undefined).format(Math.round(credits));
+}
+/** Formats a monetary amount in the given ISO 4217 currency, falling back to a plain number + code for unknown currencies. */
+export function formatMoney(amount, currency) {
+    try {
+        return new Intl.NumberFormat(undefined, { style: "currency", currency }).format(amount);
+    }
+    catch {
+        return `${amount.toFixed(2)} ${currency}`;
+    }
+}

package/dist/index.d.ts

@@ -1,7 +1,11 @@
 export { CreditsBadge, type CreditsBadgeProps } from "./CreditsBadge";
 export { PaywallModal, type PaywallModalProps, type PackageOption, type SubscriptionPlanOption, type ActiveSubscriptionInfo, } from "./PaywallModal";
 export { CreditIndicator, type CreditIndicatorProps } from "./CreditIndicator";
-export { CrediballProvider, useCrediball, type CrediballProviderProps, } from "./CrediballProvider";
+export { CrediballProvider, useCrediball, useCrediballOptional, type CrediballProviderProps, } from "./CrediballProvider";
 export { usePaywall, isInsufficientCreditsError, type UsePaywallProps, type UsePaywallResult, } from "./usePaywall";
-export { tokens, type CrediballThemeOverrides } from "./theme";
+export { tokens, theme, cssVars, accentStyle, type CrediballThemeOverrides } from "./theme";
 export { notifyInsufficientCredits } from "./creditEvent";
+export { CrediballBalance, type CrediballBalanceProps } from "./variables/CrediballBalance";
+export { CrediballUsage, type CrediballUsageProps } from "./variables/CrediballUsage";
+export { CrediballTopUpButton, type CrediballTopUpButtonProps } from "./variables/CrediballTopUpButton";
+export { CrediballLowCreditWarning, type CrediballLowCreditWarningProps, } from "./variables/CrediballLowCreditWarning";

package/dist/index.js

@@ -3,7 +3,12 @@
 export { CreditsBadge } from "./CreditsBadge";
 export { PaywallModal, } from "./PaywallModal";
 export { CreditIndicator } from "./CreditIndicator";
-export { CrediballProvider, useCrediball, } from "./CrediballProvider";
+export { CrediballProvider, useCrediball, useCrediballOptional, } from "./CrediballProvider";
 export { usePaywall, isInsufficientCreditsError, } from "./usePaywall";
-export { tokens } from "./theme";
+export { tokens, theme, cssVars, accentStyle } from "./theme";
 export { notifyInsufficientCredits } from "./creditEvent";
+// Tier 2 — "variables" you place anywhere inside <CrediballProvider>.
+export { CrediballBalance } from "./variables/CrediballBalance";
+export { CrediballUsage } from "./variables/CrediballUsage";
+export { CrediballTopUpButton } from "./variables/CrediballTopUpButton";
+export { CrediballLowCreditWarning, } from "./variables/CrediballLowCreditWarning";

package/dist/theme.d.ts

@@ -1,3 +1,4 @@
+import type { CSSProperties } from "react";
 /**
  * Self-contained design tokens (no Tailwind / external CSS) so these components
  * look right when dropped into any host app. Mirrors the Crediball design
@@ -19,3 +20,41 @@ export type CrediballThemeOverrides = {
     /** Override the accent color (defaults to Action Blue #0066cc). */
     accentColor?: string;
 };
+/**
+ * `--crediball-*` CSS custom property names. A host app can set these once
+ * (on `:root` or any ancestor) to theme every embedded component — including
+ * ones rendered later, or across `@crediball/elements` web components — without
+ * passing props. Components read these via `theme` below, which wraps each
+ * token in `var(--crediball-x, <tokens fallback>)`.
+ */
+export declare const cssVars: {
+    readonly accent: "--crediball-accent";
+    readonly ink: "--crediball-ink";
+    readonly inkMuted: "--crediball-ink-muted";
+    readonly canvas: "--crediball-canvas";
+    readonly hairline: "--crediball-hairline";
+    readonly onAccent: "--crediball-on-accent";
+    readonly overlay: "--crediball-overlay";
+    readonly radiusPill: "--crediball-radius";
+    readonly radiusCard: "--crediball-radius-card";
+    readonly font: "--crediball-font";
+};
+/** CSS-var-wrapped values for use in component styles — prefer these over raw `tokens`. */
+export declare const theme: {
+    accent: string;
+    ink: string;
+    inkMuted: string;
+    canvas: string;
+    hairline: string;
+    onAccent: string;
+    overlay: string;
+    radiusPill: string;
+    radiusCard: string;
+    font: string;
+};
+/**
+ * Sets `--crediball-accent` on a component's root element when `accentColor`
+ * is passed, so the prop keeps working exactly as before while everything
+ * underneath consistently reads `theme.accent`. Spread onto the root `style`.
+ */
+export declare function accentStyle(accentColor?: string): CSSProperties;

package/dist/theme.js

@@ -15,3 +15,46 @@ export const tokens = {
     radiusPill: 9999,
     radiusCard: 18,
 };
+/**
+ * `--crediball-*` CSS custom property names. A host app can set these once
+ * (on `:root` or any ancestor) to theme every embedded component — including
+ * ones rendered later, or across `@crediball/elements` web components — without
+ * passing props. Components read these via `theme` below, which wraps each
+ * token in `var(--crediball-x, <tokens fallback>)`.
+ */
+export const cssVars = {
+    accent: "--crediball-accent",
+    ink: "--crediball-ink",
+    inkMuted: "--crediball-ink-muted",
+    canvas: "--crediball-canvas",
+    hairline: "--crediball-hairline",
+    onAccent: "--crediball-on-accent",
+    overlay: "--crediball-overlay",
+    radiusPill: "--crediball-radius",
+    radiusCard: "--crediball-radius-card",
+    font: "--crediball-font",
+};
+function v(name, fallback) {
+    return `var(${name}, ${fallback})`;
+}
+/** CSS-var-wrapped values for use in component styles — prefer these over raw `tokens`. */
+export const theme = {
+    accent: v(cssVars.accent, tokens.primary),
+    ink: v(cssVars.ink, tokens.ink),
+    inkMuted: v(cssVars.inkMuted, tokens.inkMuted),
+    canvas: v(cssVars.canvas, tokens.canvas),
+    hairline: v(cssVars.hairline, tokens.hairline),
+    onAccent: v(cssVars.onAccent, tokens.onPrimary),
+    overlay: v(cssVars.overlay, tokens.overlay),
+    radiusPill: v(cssVars.radiusPill, `${tokens.radiusPill}px`),
+    radiusCard: v(cssVars.radiusCard, `${tokens.radiusCard}px`),
+    font: v(cssVars.font, tokens.fontStack),
+};
+/**
+ * Sets `--crediball-accent` on a component's root element when `accentColor`
+ * is passed, so the prop keeps working exactly as before while everything
+ * underneath consistently reads `theme.accent`. Spread onto the root `style`.
+ */
+export function accentStyle(accentColor) {
+    return accentColor ? { [cssVars.accent]: accentColor } : {};
+}