@traffical/react 0.1.1

package/dist/hooks.js

@@ -0,0 +1,424 @@
+/**
+ * Traffical React Hooks
+ *
+ * React hooks for parameter resolution and decision tracking.
+ * Uses the browser-optimized JS Client for full feature support.
+ */
+import { useState, useEffect, useCallback, useRef } from "react";
+import { resolveParameters } from "@traffical/core";
+import { useTrafficalContext } from "./context.js";
+// =============================================================================
+// Internal Utilities
+// =============================================================================
+/**
+ * Creates a stable string key from an object for use in dependency arrays.
+ * This prevents infinite re-renders when users pass inline objects to hooks.
+ *
+ * Uses JSON.stringify with sorted keys to ensure consistent ordering.
+ */
+function createStableKey(obj) {
+    if (obj === null || obj === undefined) {
+        return String(obj);
+    }
+    if (typeof obj !== "object") {
+        return String(obj);
+    }
+    // Sort keys for consistent ordering
+    return JSON.stringify(obj, Object.keys(obj).sort());
+}
+/**
+ * Custom hook that returns a stable reference to an object.
+ * Only updates the reference when the object's serialized value changes.
+ *
+ * This allows users to pass inline objects without causing infinite re-renders:
+ * ```tsx
+ * // This now works without memoization!
+ * const { params } = useTraffical({
+ *   defaults: { 'ui.color': '#000' }, // inline object is fine
+ * });
+ * ```
+ */
+function useStableObject(obj) {
+    const stableKey = createStableKey(obj);
+    const ref = useRef(obj);
+    // Only update the ref when the serialized value actually changes
+    // This is safe because we're comparing by value, not reference
+    if (createStableKey(ref.current) !== stableKey) {
+        ref.current = obj;
+    }
+    return ref.current;
+}
+/**
+ * Primary hook for Traffical parameter resolution and decision tracking.
+ *
+ * On first render, returns defaults immediately (no blocking).
+ * When the config bundle loads, recomputes and returns resolved values.
+ *
+ * @example
+ * ```tsx
+ * // Full tracking (default) - decision + exposure events
+ * const { params, decision, ready } = useTraffical({
+ *   defaults: { "checkout.ctaText": "Buy Now" },
+ * });
+ *
+ * // Decision tracking only - manual exposure control
+ * const { params, decision, trackExposure } = useTraffical({
+ *   defaults: { "checkout.ctaText": "Buy Now" },
+ *   tracking: "decision",
+ * });
+ *
+ * // No tracking - for SSR, tests, or internal logic
+ * const { params, ready } = useTraffical({
+ *   defaults: { "ui.hero.title": "Welcome" },
+ *   tracking: "none",
+ * });
+ * ```
+ */
+export function useTraffical(options) {
+    const { client, ready, error, getContext, getUnitKey, initialParams, localConfig } = useTrafficalContext();
+    const trackingMode = options.tracking ?? "full";
+    const shouldTrackDecision = trackingMode !== "none";
+    const shouldAutoTrackExposure = trackingMode === "full";
+    // Create stable references for objects to prevent infinite re-renders
+    // when users pass inline objects like: useTraffical({ defaults: { ... } })
+    const stableDefaults = useStableObject(options.defaults);
+    const stableContext = useStableObject(options.context);
+    // Track if we resolved synchronously (to avoid duplicate resolution in useEffect)
+    const resolvedSyncRef = useRef(false);
+    const syncDecisionRef = useRef(null);
+    // State - resolve synchronously if possible to prevent flicker
+    const [params, setParams] = useState(() => {
+        // If client is already ready (e.g., subsequent page navigation), resolve synchronously
+        // This prevents the default -> resolved flicker (classic A/B testing problem)
+        if (client && ready) {
+            resolvedSyncRef.current = true;
+            const context = {
+                ...getContext(),
+                ...(options.context ?? {}),
+            };
+            if (shouldTrackDecision) {
+                // Use decide() for tracked decisions
+                const result = client.decide({
+                    context,
+                    defaults: options.defaults,
+                });
+                syncDecisionRef.current = result;
+                return result.assignments;
+            }
+            else {
+                // Use getParams() for untracked
+                return client.getParams({
+                    context,
+                    defaults: options.defaults,
+                });
+            }
+        }
+        // NEW: If we have localConfig bundle, resolve synchronously even before client is ready
+        // This is the key to flicker-free SSR: server and client both resolve from the same bundle
+        if (localConfig) {
+            try {
+                const context = getContext();
+                // Only resolve if we have a userId (set by server via cookie/header)
+                if (context.userId) {
+                    resolvedSyncRef.current = true;
+                    const fullContext = {
+                        ...context,
+                        ...(options.context ?? {}),
+                    };
+                    // Use pure resolution function from core - no tracking on initial render
+                    const resolved = resolveParameters(localConfig, fullContext, options.defaults);
+                    return resolved;
+                }
+            }
+            catch {
+                // Context function not ready, fall through to defaults
+            }
+        }
+        // Fallback to defaults (no localConfig or no userId)
+        if (initialParams) {
+            return { ...stableDefaults, ...initialParams };
+        }
+        return stableDefaults;
+    });
+    const [decision, setDecision] = useState(() => syncDecisionRef.current);
+    const [hasTrackedExposure, setHasTrackedExposure] = useState(false);
+    // Manual exposure tracking (synchronous - batched internally)
+    const trackExposure = useCallback(() => {
+        // No-op when tracking is "none"
+        if (trackingMode === "none") {
+            return;
+        }
+        if (!client || !decision || hasTrackedExposure) {
+            return;
+        }
+        client.trackExposure(decision);
+        setHasTrackedExposure(true);
+    }, [client, decision, hasTrackedExposure, trackingMode]);
+    // Resolve params or make decision when client is ready
+    useEffect(() => {
+        if (!client || !ready) {
+            return;
+        }
+        // Build context using stable references
+        const context = {
+            ...getContext(),
+            ...stableContext,
+        };
+        if (shouldTrackDecision) {
+            // Use decide() - tracks decision event via DecisionTrackingPlugin
+            const result = client.decide({
+                context,
+                defaults: stableDefaults,
+            });
+            // Only update state if we didn't already resolve synchronously
+            // This prevents the params from flickering (default -> resolved)
+            // But we ALWAYS call decide() to ensure tracking happens
+            if (!resolvedSyncRef.current) {
+                setParams(result.assignments);
+            }
+            setDecision(result);
+            setHasTrackedExposure(false);
+        }
+        else {
+            // Use getParams() - no tracking
+            if (!resolvedSyncRef.current) {
+                const resolved = client.getParams({
+                    context,
+                    defaults: stableDefaults,
+                });
+                setParams(resolved);
+            }
+            setDecision(null);
+        }
+        // Clear the sync flag after first effect run
+        resolvedSyncRef.current = false;
+    }, [client, ready, getContext, stableContext, stableDefaults, shouldTrackDecision]);
+    // Auto-track exposure when tracking is "full"
+    useEffect(() => {
+        if (shouldAutoTrackExposure && decision && !hasTrackedExposure) {
+            trackExposure();
+        }
+    }, [shouldAutoTrackExposure, decision, hasTrackedExposure, trackExposure]);
+    // Ref to store current decision for stable track function reference
+    const decisionRef = useRef(null);
+    decisionRef.current = decision;
+    // Buffer for track events that arrive before decision is ready
+    // This prevents race conditions where track() is called in a useEffect
+    // that runs before the decision has been set
+    const pendingTracksRef = useRef([]);
+    // Flush pending track events when decision becomes available
+    useEffect(() => {
+        if (decision && client && pendingTracksRef.current.length > 0) {
+            const pending = pendingTracksRef.current;
+            pendingTracksRef.current = [];
+            for (const { event, properties } of pending) {
+                client.track(event, properties, {
+                    decisionId: decision.decisionId,
+                    unitKey: getUnitKey(),
+                });
+            }
+        }
+    }, [decision, client, getUnitKey]);
+    // Track user events - decisionId is automatically included
+    // If decision isn't ready yet, events are queued and flushed when it becomes available
+    const track = useCallback((event, properties) => {
+        if (!client) {
+            console.warn("[Traffical] Client not initialized, cannot track event");
+            return;
+        }
+        const currentDecision = decisionRef.current;
+        if (!currentDecision) {
+            // Queue the event instead of dropping it - will be flushed when decision is ready
+            // This handles the race condition where track() is called before decision is set
+            if (trackingMode === "none") {
+                console.warn("[Traffical] Cannot track event with tracking: 'none'. Use tracking: 'full' or 'decision'.");
+                return;
+            }
+            pendingTracksRef.current.push({ event, properties });
+            return;
+        }
+        client.track(event, properties, {
+            decisionId: currentDecision.decisionId,
+            unitKey: getUnitKey(),
+        });
+    }, [client, getUnitKey, trackingMode]);
+    // Deprecated: Bound reward tracking - decisionId is automatically included
+    const trackReward = useCallback((options) => {
+        if (!client) {
+            console.warn("[Traffical] Client not initialized, cannot track reward");
+            return;
+        }
+        const currentDecision = decisionRef.current;
+        if (!currentDecision) {
+            console.warn("[Traffical] No decision available, cannot track reward. Did you use tracking: 'none'?");
+            return;
+        }
+        // Map old API to new track() API
+        track(options.rewardType || "reward", {
+            value: options.reward,
+            ...(options.rewards ? { rewards: options.rewards } : {}),
+        });
+    }, [client, track]);
+    return { params, decision, ready, error, trackExposure, track, trackReward };
+}
+/**
+ * Hook to get resolved parameter values.
+ *
+ * @deprecated Use `useTraffical({ tracking: "none" })` instead.
+ *
+ * @example
+ * ```tsx
+ * // Old way (deprecated)
+ * const { params, ready } = useTrafficalParams({ defaults: { ... } });
+ *
+ * // New way
+ * const { params, ready } = useTraffical({ defaults: { ... }, tracking: "none" });
+ * ```
+ */
+export function useTrafficalParams(options) {
+    // Show deprecation warning in development only
+    useEffect(() => {
+        if (process.env.NODE_ENV === "development") {
+            console.warn('[Traffical] useTrafficalParams is deprecated. Use useTraffical({ tracking: "none" }) instead.');
+        }
+    }, []);
+    const result = useTraffical({ ...options, tracking: "none" });
+    return { params: result.params, ready: result.ready, error: result.error };
+}
+/**
+ * Hook to get a decision with full metadata for tracking.
+ *
+ * @deprecated Use `useTraffical()` instead.
+ *
+ * @example
+ * ```tsx
+ * // Old way (deprecated)
+ * const { params, decision } = useTrafficalDecision({ defaults: { ... } });
+ *
+ * // New way
+ * const { params, decision } = useTraffical({ defaults: { ... } });
+ *
+ * // Old way with manual exposure (deprecated)
+ * const { params, trackExposure } = useTrafficalDecision({ defaults: { ... }, trackExposure: false });
+ *
+ * // New way with manual exposure
+ * const { params, trackExposure } = useTraffical({ defaults: { ... }, tracking: "decision" });
+ * ```
+ */
+export function useTrafficalDecision(options) {
+    // Show deprecation warning in development only
+    useEffect(() => {
+        if (process.env.NODE_ENV === "development") {
+            console.warn("[Traffical] useTrafficalDecision is deprecated. Use useTraffical() instead.");
+        }
+    }, []);
+    // Map old trackExposure option to new tracking mode
+    const tracking = options.trackExposure === false ? "decision" : "full";
+    return useTraffical({ defaults: options.defaults, context: options.context, tracking });
+}
+/**
+ * Hook to track user events.
+ *
+ * @example
+ * ```tsx
+ * const track = useTrafficalTrack();
+ *
+ * const handlePurchase = (amount: number) => {
+ *   track('purchase', { value: amount, orderId: 'ord_123' });
+ * };
+ * ```
+ */
+export function useTrafficalTrack() {
+    const { client, getUnitKey } = useTrafficalContext();
+    const track = useCallback((event, properties, options) => {
+        if (!client) {
+            console.warn("[Traffical] Client not initialized, cannot track event");
+            return;
+        }
+        client.track(event, properties, {
+            decisionId: options?.decisionId,
+            unitKey: getUnitKey(),
+        });
+    }, [client, getUnitKey]);
+    return track;
+}
+/**
+ * @deprecated Use useTrafficalTrack() instead.
+ *
+ * Hook to track a reward.
+ *
+ * @example
+ * ```tsx
+ * const trackReward = useTrafficalReward();
+ *
+ * const handlePurchase = (amount: number) => {
+ *   trackReward({
+ *     decisionId: decision.decisionId,
+ *     reward: amount,
+ *     rewardType: "revenue",
+ *   });
+ * };
+ * ```
+ */
+export function useTrafficalReward() {
+    const { client, getUnitKey, getContext } = useTrafficalContext();
+    const trackReward = useCallback((options) => {
+        if (!client) {
+            console.warn("[Traffical] Client not initialized, cannot track reward");
+            return;
+        }
+        // Map old API to new track() API
+        client.track(options.rewardType || "reward", {
+            value: options.reward,
+            ...(options.rewards ? { rewards: options.rewards } : {}),
+        }, {
+            decisionId: options.decisionId,
+            unitKey: getUnitKey(),
+        });
+    }, [client, getUnitKey, getContext]);
+    return trackReward;
+}
+/**
+ * Hook to access a registered plugin by name.
+ *
+ * @example
+ * ```tsx
+ * import { createDOMBindingPlugin, DOMBindingPlugin } from '@traffical/js-client';
+ *
+ * // In your provider config:
+ * plugins: [createDOMBindingPlugin()]
+ *
+ * // In a component:
+ * const domPlugin = useTrafficalPlugin<DOMBindingPlugin>('dom-binding');
+ *
+ * // Re-apply bindings after dynamic content changes
+ * useEffect(() => {
+ *   domPlugin?.applyBindings();
+ * }, [contentLoaded, domPlugin]);
+ * ```
+ */
+export function useTrafficalPlugin(name) {
+    const { client, ready } = useTrafficalContext();
+    if (!client || !ready) {
+        return undefined;
+    }
+    return client.getPlugin(name);
+}
+/**
+ * Hook to access the Traffical client directly.
+ *
+ * @example
+ * ```tsx
+ * const { client, ready } = useTrafficalClient();
+ *
+ * if (ready && client) {
+ *   const version = client.getConfigVersion();
+ *   const stableId = client.getStableId();
+ * }
+ * ```
+ */
+export function useTrafficalClient() {
+    const { client, ready, error } = useTrafficalContext();
+    return { client, ready, error };
+}
+//# sourceMappingURL=hooks.js.map

package/dist/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @traffical/react
+ *
+ * Traffical SDK for React applications.
+ * Provides Provider and hooks for parameter resolution and decision tracking.
+ *
+ * Features:
+ * - Browser-optimized with sendBeacon, localStorage persistence
+ * - Automatic stable ID for anonymous users
+ * - Plugin system support (DecisionTrackingPlugin enabled by default)
+ * - Decision and exposure deduplication
+ *
+ * @example
+ * ```tsx
+ * import { TrafficalProvider, useTraffical } from '@traffical/react';
+ *
+ * function App() {
+ *   return (
+ *     <TrafficalProvider
+ *       config={{
+ *         orgId: 'org_123',
+ *         projectId: 'proj_456',
+ *         env: 'production',
+ *         apiKey: 'pk_...',
+ *       }}
+ *     >
+ *       <MyComponent />
+ *     </TrafficalProvider>
+ *   );
+ * }
+ *
+ * function MyComponent() {
+ *   const { params, ready } = useTraffical({
+ *     defaults: { 'ui.hero.title': 'Welcome' },
+ *   });
+ *
+ *   if (!ready) return <div>Loading...</div>;
+ *   return <h1>{params['ui.hero.title']}</h1>;
+ * }
+ * ```
+ */
+export * from "@traffical/core";
+export { TrafficalClient, createTrafficalClient, createTrafficalClientSync, type TrafficalClientOptions, } from "@traffical/js-client";
+export { type TrafficalPlugin, type PluginOptions, createDOMBindingPlugin, type DOMBindingPlugin, type DOMBindingPluginOptions, } from "@traffical/js-client";
+export { TrafficalProvider, type TrafficalProviderProps } from "./provider.js";
+export { TrafficalContext, useTrafficalContext, type TrafficalProviderConfig, type TrafficalContextValue, } from "./context.js";
+export { useTraffical, type UseTrafficalOptions, type UseTrafficalResult, type BoundTrackOptions, useTrafficalTrack, useTrafficalPlugin, useTrafficalClient, type BoundTrackRewardOptions, useTrafficalReward, useTrafficalParams, useTrafficalDecision, type UseTrafficalParamsOptions, type UseTrafficalParamsResult, type UseTrafficalDecisionOptions, type UseTrafficalDecisionResult, } from "./hooks.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAGH,cAAc,iBAAiB,CAAC;AAGhC,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,yBAAyB,EACzB,KAAK,sBAAsB,GAC5B,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC7B,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,iBAAiB,EAAE,KAAK,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAE/E,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,GAC3B,MAAM,cAAc,CAAC;AAEtB,OAAO,EAEL,YAAY,EACZ,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EAEtB,iBAAiB,EAEjB,kBAAkB,EAClB,kBAAkB,EAElB,KAAK,uBAAuB,EAC5B,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,GAChC,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,58 @@
+/**
+ * @traffical/react
+ *
+ * Traffical SDK for React applications.
+ * Provides Provider and hooks for parameter resolution and decision tracking.
+ *
+ * Features:
+ * - Browser-optimized with sendBeacon, localStorage persistence
+ * - Automatic stable ID for anonymous users
+ * - Plugin system support (DecisionTrackingPlugin enabled by default)
+ * - Decision and exposure deduplication
+ *
+ * @example
+ * ```tsx
+ * import { TrafficalProvider, useTraffical } from '@traffical/react';
+ *
+ * function App() {
+ *   return (
+ *     <TrafficalProvider
+ *       config={{
+ *         orgId: 'org_123',
+ *         projectId: 'proj_456',
+ *         env: 'production',
+ *         apiKey: 'pk_...',
+ *       }}
+ *     >
+ *       <MyComponent />
+ *     </TrafficalProvider>
+ *   );
+ * }
+ *
+ * function MyComponent() {
+ *   const { params, ready } = useTraffical({
+ *     defaults: { 'ui.hero.title': 'Welcome' },
+ *   });
+ *
+ *   if (!ready) return <div>Loading...</div>;
+ *   return <h1>{params['ui.hero.title']}</h1>;
+ * }
+ * ```
+ */
+// Re-export everything from core
+export * from "@traffical/core";
+// Re-export client and utilities from JS Client
+export { TrafficalClient, createTrafficalClient, createTrafficalClientSync, } from "@traffical/js-client";
+// Re-export plugin utilities from JS Client
+export { createDOMBindingPlugin, } from "@traffical/js-client";
+// Export React-specific components and hooks
+export { TrafficalProvider } from "./provider.js";
+export { TrafficalContext, useTrafficalContext, } from "./context.js";
+export { 
+// Primary hook
+useTraffical, 
+// Track hook
+useTrafficalTrack, 
+// Other hooks
+useTrafficalPlugin, useTrafficalClient, useTrafficalReward, useTrafficalParams, useTrafficalDecision, } from "./hooks.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,iCAAiC;AACjC,cAAc,iBAAiB,CAAC;AAEhC,gDAAgD;AAChD,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,yBAAyB,GAE1B,MAAM,sBAAsB,CAAC;AAE9B,4CAA4C;AAC5C,OAAO,EAGL,sBAAsB,GAGvB,MAAM,sBAAsB,CAAC;AAE9B,6CAA6C;AAC7C,OAAO,EAAE,iBAAiB,EAA+B,MAAM,eAAe,CAAC;AAE/E,OAAO,EACL,gBAAgB,EAChB,mBAAmB,GAGpB,MAAM,cAAc,CAAC;AAEtB,OAAO;AACL,eAAe;AACf,YAAY;AAIZ,aAAa;AACb,iBAAiB;AACjB,cAAc;AACd,kBAAkB,EAClB,kBAAkB,EAGlB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GAKrB,MAAM,YAAY,CAAC"}

package/dist/provider.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Traffical React Provider
+ *
+ * Initializes the Traffical client (browser-optimized) and provides it to child components.
+ * Supports plugins, automatic stable ID, and decision tracking out of the box.
+ */
+import React, { type ReactNode } from "react";
+import { type TrafficalProviderConfig } from "./context.js";
+/**
+ * Props for the TrafficalProvider component.
+ */
+export interface TrafficalProviderProps {
+    /** Configuration for the Traffical client */
+    config: TrafficalProviderConfig;
+    /** Child components */
+    children: ReactNode;
+}
+/**
+ * TrafficalProvider - initializes and provides the Traffical client to React components.
+ *
+ * Features:
+ * - Browser-optimized with sendBeacon, localStorage persistence
+ * - Automatic stable ID for anonymous users (unless unitKeyFn provided)
+ * - Plugin system support (DecisionTrackingPlugin enabled by default)
+ * - Decision and exposure deduplication
+ *
+ * @example
+ * ```tsx
+ * <TrafficalProvider
+ *   config={{
+ *     orgId: "org_123",
+ *     projectId: "proj_456",
+ *     env: "production",
+ *     apiKey: "pk_...",
+ *     // Optional: provide unitKeyFn for logged-in users
+ *     unitKeyFn: () => getUserId(),
+ *     // Optional: add context
+ *     contextFn: () => ({ locale: "en-US" }),
+ *     // Optional: add custom plugins
+ *     plugins: [createDOMBindingPlugin()],
+ *   }}
+ * >
+ *   <App />
+ * </TrafficalProvider>
+ * ```
+ */
+export declare function TrafficalProvider({ config, children, }: TrafficalProviderProps): React.ReactElement;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,EAMZ,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAMf,OAAO,EAEL,KAAK,uBAAuB,EAE7B,MAAM,cAAc,CAAC;AAEtB;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,6CAA6C;IAC7C,MAAM,EAAE,uBAAuB,CAAC;IAChC,uBAAuB;IACvB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,MAAM,EACN,QAAQ,GACT,EAAE,sBAAsB,GAAG,KAAK,CAAC,YAAY,CA6H7C"}