@cavi-ai/api-client 0.1.0

package/dist/react/gateway-provider.js

@@ -0,0 +1,569 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
+import { normalizeGatewayStreamFailure } from "../core/gateway/run/stream-failure.js";
+import { GatewayRpcError, } from "../core/gateway/rpc/client.js";
+import { GatewayWebSocketClient, tryResolveGatewayTargets, } from "../core/ws/index.js";
+const GatewayRpcClient = GatewayWebSocketClient;
+const GatewayClientContext = createContext(null);
+function resolveGatewayRpcClientOptions(params) {
+    return {
+        ...params.gatewayClientOverrides,
+        clientId: params.clientId,
+        clientVersion: params.clientVersion,
+        requestedScopes: params.requestedScopes,
+        preauthHandshakeTimeoutMs: params.preauthHandshakeTimeoutMs,
+        enableDeviceIdentity: params.enableDeviceIdentity,
+        clientPlatform: params.clientPlatform,
+        clientMode: params.clientMode,
+        onRpcTrace: params.onRpcTrace,
+        deviceIdentityLoader: params.deviceIdentityLoader,
+    };
+}
+function buildGatewayClientConnectionKey(params) {
+    if (!params.wsUrl || !params.authToken) {
+        return null;
+    }
+    return JSON.stringify({
+        wsUrl: params.wsUrl,
+        authToken: params.authToken,
+        clientId: params.clientOptions.clientId ?? null,
+        clientVersion: params.clientOptions.clientVersion ?? null,
+        requestedScopes: params.clientOptions.requestedScopes
+            ? [...params.clientOptions.requestedScopes]
+            : null,
+        defaultRequestedScopes: params.clientOptions.defaultRequestedScopes
+            ? [...params.clientOptions.defaultRequestedScopes]
+            : null,
+        preauthHandshakeTimeoutMs: params.clientOptions.preauthHandshakeTimeoutMs ?? null,
+        preauthHandshakeEnv: params.clientOptions.preauthHandshakeEnv ?? null,
+        preauthHandshakeEnvKeys: params.clientOptions.preauthHandshakeEnvKeys ?? null,
+        requestTimeoutMs: params.clientOptions.requestTimeoutMs ?? null,
+        maxConcurrentRequests: params.clientOptions.maxConcurrentRequests ?? null,
+        minProtocol: params.clientOptions.minProtocol ?? null,
+        maxProtocol: params.clientOptions.maxProtocol ?? null,
+        enableDeviceIdentity: params.clientOptions.enableDeviceIdentity ?? null,
+        clientPlatform: params.clientOptions.clientPlatform ?? null,
+        clientMode: params.clientOptions.clientMode ?? null,
+    });
+}
+/**
+ * Manages GatewayRpcClient lifecycle and provides it via context.
+ * Call connect() to establish the WebSocket connection.
+ */
+export function useGatewayClient(options) {
+    const { gatewayBaseUrl, authToken, clientId, clientVersion, requestedScopes, preauthHandshakeTimeoutMs, gatewayClientOverrides, enableDeviceIdentity, clientPlatform, clientMode, autoReconnect = false, onRpcTrace, deviceIdentityLoader, } = options;
+    const onRpcTraceRef = useRef(onRpcTrace);
+    onRpcTraceRef.current = onRpcTrace;
+    const target = useMemo(() => tryResolveGatewayTargets(gatewayBaseUrl ?? ""), [gatewayBaseUrl]);
+    const clientOptions = useMemo(() => resolveGatewayRpcClientOptions({
+        clientId,
+        clientVersion,
+        requestedScopes,
+        preauthHandshakeTimeoutMs,
+        gatewayClientOverrides,
+        enableDeviceIdentity,
+        clientPlatform,
+        clientMode,
+        onRpcTrace: (entry) => {
+            onRpcTraceRef.current?.(entry);
+        },
+        deviceIdentityLoader,
+    }), [
+        clientId,
+        clientVersion,
+        requestedScopes,
+        preauthHandshakeTimeoutMs,
+        gatewayClientOverrides,
+        enableDeviceIdentity,
+        clientPlatform,
+        clientMode,
+        deviceIdentityLoader,
+    ]);
+    const connectionKey = useMemo(() => buildGatewayClientConnectionKey({
+        wsUrl: target?.wsUrl ?? null,
+        authToken,
+        clientOptions,
+    }), [target?.wsUrl, authToken, clientOptions]);
+    const [client, setClient] = useState(null);
+    const [state, setState] = useState("idle");
+    const [connectionError, setConnectionError] = useState(null);
+    const [urlError, setUrlError] = useState(null);
+    const clientRef = useRef(null);
+    const clientKeyRef = useRef(null);
+    const clientStateUnsubscribeRef = useRef(null);
+    const connectPromiseRef = useRef(null);
+    const reconnectTimerRef = useRef(null);
+    const reconnectAttemptRef = useRef(0);
+    const clearClientSubscription = () => {
+        if (clientStateUnsubscribeRef.current) {
+            clientStateUnsubscribeRef.current();
+            clientStateUnsubscribeRef.current = null;
+        }
+    };
+    const trackConnectPromise = (promise) => {
+        const tracked = promise.finally(() => {
+            if (connectPromiseRef.current === tracked) {
+                connectPromiseRef.current = null;
+            }
+        });
+        connectPromiseRef.current = tracked;
+        return tracked;
+    };
+    const disconnectCurrentClient = useCallback(async () => {
+        if (reconnectTimerRef.current !== null) {
+            clearTimeout(reconnectTimerRef.current);
+            reconnectTimerRef.current = null;
+        }
+        reconnectAttemptRef.current = 0;
+        const c = clientRef.current;
+        connectPromiseRef.current = null;
+        clientKeyRef.current = null;
+        clientRef.current = null;
+        clearClientSubscription();
+        setClient(null);
+        setState("idle");
+        setConnectionError(null);
+        if (c) {
+            await c.close();
+        }
+    }, []);
+    const connect = useCallback(async () => {
+        if (!target || !authToken || !connectionKey) {
+            return;
+        }
+        const existing = clientRef.current;
+        if (existing && clientKeyRef.current === connectionKey) {
+            if (existing.getConnectionState() === "connected") {
+                return;
+            }
+            if (connectPromiseRef.current) {
+                await connectPromiseRef.current;
+                return;
+            }
+            await trackConnectPromise(existing.connect());
+            return;
+        }
+        if (reconnectTimerRef.current !== null) {
+            clearTimeout(reconnectTimerRef.current);
+            reconnectTimerRef.current = null;
+        }
+        reconnectAttemptRef.current = 0;
+        const prev = clientRef.current;
+        connectPromiseRef.current = null;
+        clearClientSubscription();
+        clientKeyRef.current = null;
+        clientRef.current = null;
+        const c = new GatewayRpcClient(target.wsUrl, authToken, clientOptions);
+        clientKeyRef.current = connectionKey;
+        clientRef.current = c;
+        setClient(c);
+        clientStateUnsubscribeRef.current = c.onStateChange((s, e) => {
+            setState(s);
+            setConnectionError(e);
+        });
+        if (prev) {
+            void prev.close();
+        }
+        await trackConnectPromise(c.connect());
+    }, [target, authToken, clientOptions, connectionKey]);
+    const disconnect = useCallback(async () => {
+        await disconnectCurrentClient();
+    }, [disconnectCurrentClient]);
+    const connectRef = useRef(connect);
+    connectRef.current = connect;
+    useEffect(() => {
+        if (!autoReconnect) {
+            if (reconnectTimerRef.current !== null) {
+                clearTimeout(reconnectTimerRef.current);
+                reconnectTimerRef.current = null;
+            }
+            return;
+        }
+        if (!connectionKey || urlError) {
+            return;
+        }
+        if (state === "connecting" || state === "connected") {
+            if (reconnectTimerRef.current !== null) {
+                clearTimeout(reconnectTimerRef.current);
+                reconnectTimerRef.current = null;
+            }
+            if (state === "connected") {
+                reconnectAttemptRef.current = 0;
+            }
+            return;
+        }
+        if (state !== "error" || !connectionError) {
+            return;
+        }
+        const norm = normalizeGatewayStreamFailure(connectionError);
+        if (!norm.retryable) {
+            return;
+        }
+        if (reconnectTimerRef.current !== null) {
+            return;
+        }
+        const attempt = reconnectAttemptRef.current;
+        const delayMs = computeReconnectDelay(attempt);
+        reconnectAttemptRef.current = attempt + 1;
+        setState("reconnecting");
+        reconnectTimerRef.current = setTimeout(() => {
+            reconnectTimerRef.current = null;
+            void connectRef.current();
+        }, delayMs);
+    }, [autoReconnect, state, connectionError, connectionKey, urlError]);
+    useEffect(() => {
+        if (!connectionKey) {
+            if (clientRef.current) {
+                void disconnectCurrentClient();
+            }
+            return;
+        }
+        if (clientRef.current && clientKeyRef.current !== connectionKey) {
+            void connectRef.current();
+        }
+    }, [connectionKey, disconnectCurrentClient]);
+    useEffect(() => {
+        return () => {
+            void disconnectCurrentClient();
+        };
+    }, [disconnectCurrentClient]);
+    useEffect(() => {
+        const trimmed = gatewayBaseUrl?.trim() ?? "";
+        if (!trimmed) {
+            setUrlError(null);
+            return;
+        }
+        if (!target) {
+            setUrlError(new Error("Invalid gateway URL. Use a full URL such as http://127.0.0.1:18789 (or https://, ws://, wss://)."));
+            return;
+        }
+        setUrlError(null);
+    }, [gatewayBaseUrl, target]);
+    return {
+        client,
+        state,
+        urlError,
+        connectionError,
+        error: urlError ?? connectionError,
+        connect,
+        disconnect,
+    };
+}
+/**
+ * Hook to call a gateway RPC method and optionally refresh on relevant events.
+ */
+export function useGatewayRpc(client, method, params = {}, options) {
+    const [data, setData] = useState(options?.defaultData ?? null);
+    const [error, setError] = useState(null);
+    const [loading, setLoading] = useState(false);
+    const deps = options?.deps ?? [];
+    const refreshOnEvents = options?.refreshOnEvents ?? [];
+    const refresh = useCallback(async () => {
+        if (!client) {
+            return;
+        }
+        setLoading(true);
+        setError(null);
+        try {
+            const result = await client.request(method, params);
+            setData(result);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new GatewayRpcError(String(err)));
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client, method, JSON.stringify(params), ...deps]);
+    useEffect(() => {
+        void refresh();
+    }, [refresh]);
+    useEffect(() => {
+        if (!client || refreshOnEvents.length === 0) {
+            return undefined;
+        }
+        const eventSet = new Set(refreshOnEvents);
+        const unsubscribe = client.onEvent((event) => {
+            if (eventSet.has(event.event)) {
+                void refresh();
+            }
+        });
+        return () => {
+            unsubscribe();
+        };
+    }, [client, refresh, JSON.stringify(refreshOnEvents)]);
+    return { data, error, loading, refresh };
+}
+/**
+ * Subscribe to specific gateway event types.
+ */
+export function useGatewayEvents(client, filter, handler) {
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
+    useEffect(() => {
+        if (!client) {
+            return undefined;
+        }
+        const predicate = typeof filter === "function"
+            ? filter
+            : Array.isArray(filter)
+                ? (e) => filter.includes(e.event)
+                : (e) => e.event === filter;
+        const unsubscribe = client.onEvent((event) => {
+            if (predicate(event)) {
+                handlerRef.current(event);
+            }
+        });
+        return () => {
+            unsubscribe();
+        };
+    }, [client, filter]);
+}
+/**
+ * Hook for connection status to drive UI indicators.
+ */
+export function useGatewayConnectionState(client) {
+    const [state, setState] = useState("idle");
+    useEffect(() => {
+        if (!client) {
+            setState("idle");
+            return undefined;
+        }
+        setState(client.getConnectionState());
+        const unsubscribe = client.onStateChange((s, _e) => {
+            setState(s);
+        });
+        return () => {
+            unsubscribe();
+        };
+    }, [client]);
+    return state;
+}
+const RECONNECT_BASE_DELAY_MS = 1_000;
+const RECONNECT_MAX_DELAY_MS = 15_000;
+const RECONNECT_JITTER_RATIO = 0.2;
+function computeReconnectDelay(attempt) {
+    const exponentialDelay = Math.min(RECONNECT_MAX_DELAY_MS, RECONNECT_BASE_DELAY_MS * 2 ** Math.max(0, attempt));
+    const jitterSpan = Math.round(exponentialDelay * RECONNECT_JITTER_RATIO);
+    const jitter = jitterSpan > 0 ? Math.round((Math.random() * 2 - 1) * jitterSpan) : 0;
+    return Math.max(RECONNECT_BASE_DELAY_MS, exponentialDelay + jitter);
+}
+/**
+ * Manages gateway WebSocket connection with auto-reconnect and event forwarding.
+ * Drop-in replacement for the Cavi Control UI useGatewayEventStream hook.
+ *
+ * When the gateway uses a custom pre-auth handshake window, pass the same value
+ * as `preauthHandshakeTimeoutMs` so browser clients align token-only connect timing.
+ */
+export function useGatewayEventStream(params) {
+    const target = useMemo(() => tryResolveGatewayTargets(params.gatewayBaseUrl ?? ""), [params.gatewayBaseUrl]);
+    const clientOptions = useMemo(() => resolveGatewayRpcClientOptions({
+        clientId: params.clientId,
+        clientVersion: params.clientVersion,
+        requestedScopes: params.requestedScopes,
+        preauthHandshakeTimeoutMs: params.preauthHandshakeTimeoutMs,
+        gatewayClientOverrides: params.gatewayClientOverrides,
+        enableDeviceIdentity: params.enableDeviceIdentity,
+    }), [
+        params.clientId,
+        params.clientVersion,
+        params.requestedScopes,
+        params.preauthHandshakeTimeoutMs,
+        params.gatewayClientOverrides,
+        params.enableDeviceIdentity,
+    ]);
+    const client = useMemo(() => {
+        if (!target || !params.authToken) {
+            return null;
+        }
+        return new GatewayRpcClient(target.wsUrl, params.authToken, clientOptions);
+    }, [target, params.authToken, clientOptions]);
+    const enabled = params.enabled !== false;
+    const trackLastEventAt = params.trackLastEventAt !== false;
+    const [streamState, setStreamState] = useState({
+        state: !client || !enabled ? "idle" : "connecting",
+        error: null,
+        connectedAt: null,
+        lastEventAt: null,
+    });
+    const onEventRef = useRef(params.onEvent);
+    useEffect(() => {
+        onEventRef.current = params.onEvent;
+    }, [params.onEvent]);
+    useEffect(() => {
+        setStreamState((prev) => prev.lastEventAt === null
+            ? prev
+            : {
+                ...prev,
+                lastEventAt: null,
+            });
+    }, [client, trackLastEventAt]);
+    useEffect(() => {
+        if (!client) {
+            setStreamState({
+                state: "idle",
+                error: null,
+                connectedAt: null,
+                lastEventAt: null,
+            });
+            return undefined;
+        }
+        let cancelled = false;
+        let reconnectTimer = null;
+        let reconnectAttempts = 0;
+        let hadConnected = false;
+        const clearReconnectTimer = () => {
+            if (reconnectTimer !== null) {
+                clearTimeout(reconnectTimer);
+                reconnectTimer = null;
+            }
+        };
+        const connect = () => {
+            if (cancelled) {
+                return;
+            }
+            void client.connect().catch((error) => {
+                if (cancelled) {
+                    return;
+                }
+                const norm = normalizeGatewayStreamFailure(error);
+                if (norm.retryable) {
+                    scheduleReconnect(norm.error);
+                    return;
+                }
+                clearReconnectTimer();
+                setStreamState((prev) => ({
+                    ...prev,
+                    state: norm.state,
+                    error: norm.error,
+                }));
+            });
+        };
+        const scheduleReconnect = (message) => {
+            if (cancelled || reconnectTimer !== null) {
+                return;
+            }
+            const delayMs = computeReconnectDelay(reconnectAttempts);
+            reconnectAttempts += 1;
+            setStreamState((prev) => ({
+                ...prev,
+                state: "reconnecting",
+                error: message ?? "gateway websocket closed",
+            }));
+            reconnectTimer = setTimeout(() => {
+                reconnectTimer = null;
+                connect();
+            }, delayMs);
+        };
+        if (!enabled) {
+            void client.close();
+            setStreamState((prev) => prev.state === "idle"
+                ? prev
+                : {
+                    ...prev,
+                    state: "idle",
+                });
+            return undefined;
+        }
+        setStreamState((prev) => ({
+            ...prev,
+            state: "connecting",
+            error: null,
+        }));
+        const unsubscribeState = client.onStateChange((state, error) => {
+            if (cancelled) {
+                return;
+            }
+            if (state === "connected") {
+                hadConnected = true;
+                reconnectAttempts = 0;
+                clearReconnectTimer();
+                setStreamState((prev) => ({
+                    ...prev,
+                    state: "connected",
+                    error: null,
+                    connectedAt: Date.now(),
+                }));
+                return;
+            }
+            if (state === "connecting") {
+                setStreamState((prev) => ({
+                    ...prev,
+                    state: hadConnected || reconnectAttempts > 0 ? "reconnecting" : "connecting",
+                    error: prev.state === "reconnecting" ? prev.error : null,
+                }));
+                return;
+            }
+            if (state === "error") {
+                const norm = normalizeGatewayStreamFailure(error);
+                if (norm.retryable) {
+                    scheduleReconnect(norm.error);
+                    return;
+                }
+                clearReconnectTimer();
+                setStreamState((prev) => ({ ...prev, state: norm.state, error: norm.error }));
+                return;
+            }
+            if (state === "idle" && hadConnected) {
+                scheduleReconnect(error?.message ?? null);
+                return;
+            }
+            clearReconnectTimer();
+            setStreamState((prev) => ({
+                ...prev,
+                state: "idle",
+                error: null,
+                connectedAt: null,
+            }));
+        });
+        const unsubscribeEvents = client.onEvent((event) => {
+            if (trackLastEventAt) {
+                setStreamState((prev) => ({
+                    ...prev,
+                    lastEventAt: Date.now(),
+                }));
+            }
+            onEventRef.current(event);
+        });
+        connect();
+        return () => {
+            cancelled = true;
+            clearReconnectTimer();
+            unsubscribeEvents();
+            unsubscribeState();
+            void client.close();
+        };
+    }, [client, enabled, trackLastEventAt]);
+    return { ...streamState, client };
+}
+/**
+ * Provider that creates and manages a shared GatewayRpcClient for the subtree.
+ */
+export function GatewayClientProvider({ gatewayBaseUrl, authToken, clientId, clientVersion, requestedScopes, preauthHandshakeTimeoutMs, gatewayClientOverrides, enableDeviceIdentity, clientPlatform, clientMode, autoReconnect, onRpcTrace, deviceIdentityLoader, children, }) {
+    const value = useGatewayClient({
+        gatewayBaseUrl,
+        authToken,
+        clientId,
+        clientVersion,
+        requestedScopes,
+        preauthHandshakeTimeoutMs,
+        gatewayClientOverrides,
+        enableDeviceIdentity,
+        clientPlatform,
+        clientMode,
+        autoReconnect,
+        onRpcTrace,
+        deviceIdentityLoader,
+    });
+    return _jsx(GatewayClientContext.Provider, { value: value, children: children });
+}
+/**
+ * Access the gateway client from context.
+ */
+export function useGatewayClientContext() {
+    const ctx = useContext(GatewayClientContext);
+    if (!ctx) {
+        throw new Error("useGatewayClientContext must be used within GatewayClientProvider");
+    }
+    return ctx;
+}

package/dist/react/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./gateway-provider.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC"}

package/dist/react/index.js

@@ -0,0 +1 @@
+export * from "./gateway-provider.js";

package/docs/assets/api-client-hero.svg

@@ -0,0 +1,73 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="520" viewBox="0 0 1280 520" role="img" aria-labelledby="title desc">
+  <title id="title">@cavi-ai/api-client architecture</title>
+  <desc id="desc">A gateway-agnostic TypeScript client connecting core HTTP and WebSocket transports to providers, React clients, and CAVI extensions.</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#101828"/>
+      <stop offset="0.52" stop-color="#15384d"/>
+      <stop offset="1" stop-color="#1b4b45"/>
+    </linearGradient>
+    <linearGradient id="core" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#f8fafc"/>
+      <stop offset="1" stop-color="#dff7ef"/>
+    </linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="14" stdDeviation="18" flood-color="#020617" flood-opacity="0.32"/>
+    </filter>
+  </defs>
+  <rect width="1280" height="520" rx="34" fill="url(#bg)"/>
+  <path d="M94 101 C213 25 327 58 430 101 C560 155 640 80 756 72 C889 63 1007 135 1185 83" fill="none" stroke="#5eead4" stroke-width="2" opacity="0.28"/>
+  <path d="M81 413 C238 318 397 382 519 421 C642 461 772 410 886 360 C996 313 1102 322 1210 392" fill="none" stroke="#93c5fd" stroke-width="2" opacity="0.24"/>
+
+  <g font-family="Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif">
+    <text x="70" y="89" fill="#ecfeff" font-size="52" font-weight="800" letter-spacing="0">@cavi-ai/api-client</text>
+    <text x="72" y="126" fill="#bae6fd" font-size="20">one gateway-agnostic TypeScript surface for agent runtimes</text>
+
+    <g filter="url(#shadow)">
+      <rect x="440" y="156" width="400" height="210" rx="24" fill="url(#core)"/>
+      <text x="640" y="218" fill="#0f172a" font-size="34" font-weight="800" text-anchor="middle">core contract</text>
+      <text x="640" y="255" fill="#164e63" font-size="18" text-anchor="middle">HTTP + WebSocket + SSE + RPC</text>
+      <rect x="500" y="292" width="116" height="44" rx="22" fill="#0f766e"/>
+      <text x="558" y="320" fill="#f0fdfa" font-size="15" font-weight="700" text-anchor="middle">paths</text>
+      <rect x="632" y="292" width="116" height="44" rx="22" fill="#2563eb"/>
+      <text x="690" y="320" fill="#eff6ff" font-size="15" font-weight="700" text-anchor="middle">types</text>
+      <rect x="764" y="292" width="28" height="44" rx="14" fill="#f59e0b"/>
+    </g>
+
+    <g fill="none" stroke="#d9f99d" stroke-width="3" stroke-linecap="round" opacity="0.82">
+      <path d="M352 202 H438"/>
+      <path d="M352 318 H438"/>
+      <path d="M842 202 H927"/>
+      <path d="M842 318 H927"/>
+    </g>
+
+    <g filter="url(#shadow)">
+      <rect x="70" y="164" width="280" height="78" rx="18" fill="#0f172a" stroke="#67e8f9"/>
+      <text x="210" y="196" fill="#e0f2fe" font-size="18" font-weight="800" text-anchor="middle">providers</text>
+      <text x="210" y="222" fill="#bfdbfe" font-size="15" text-anchor="middle">Hermes, OpenClaw, yours</text>
+
+      <rect x="70" y="280" width="280" height="78" rx="18" fill="#0f172a" stroke="#bef264"/>
+      <text x="210" y="312" fill="#f7fee7" font-size="18" font-weight="800" text-anchor="middle">extensions</text>
+      <text x="210" y="338" fill="#d9f99d" font-size="15" text-anchor="middle">CAVI control, teams, portals</text>
+
+      <rect x="930" y="164" width="280" height="78" rx="18" fill="#0f172a" stroke="#93c5fd"/>
+      <text x="1070" y="196" fill="#eff6ff" font-size="18" font-weight="800" text-anchor="middle">clients</text>
+      <text x="1070" y="222" fill="#dbeafe" font-size="15" text-anchor="middle">web, mobile, React</text>
+
+      <rect x="930" y="280" width="280" height="78" rx="18" fill="#0f172a" stroke="#fbbf24"/>
+      <text x="1070" y="312" fill="#fffbeb" font-size="18" font-weight="800" text-anchor="middle">fallbacks</text>
+      <text x="1070" y="338" fill="#fde68a" font-size="15" text-anchor="middle">typed envelopes, panel-safe failure</text>
+    </g>
+
+    <g>
+      <rect x="72" y="432" width="168" height="44" rx="22" fill="#ecfeff" opacity="0.96"/>
+      <text x="156" y="460" fill="#0f172a" font-size="15" font-weight="800" text-anchor="middle">zero runtime deps</text>
+      <rect x="256" y="432" width="132" height="44" rx="22" fill="#ecfeff" opacity="0.96"/>
+      <text x="322" y="460" fill="#0f172a" font-size="15" font-weight="800" text-anchor="middle">pure ESM</text>
+      <rect x="404" y="432" width="146" height="44" rx="22" fill="#ecfeff" opacity="0.96"/>
+      <text x="477" y="460" fill="#0f172a" font-size="15" font-weight="800" text-anchor="middle">Node 20+</text>
+      <rect x="566" y="432" width="206" height="44" rx="22" fill="#ecfeff" opacity="0.96"/>
+      <text x="669" y="460" fill="#0f172a" font-size="15" font-weight="800" text-anchor="middle">provider modules</text>
+    </g>
+  </g>
+</svg>