@farcaster/snap 2.0.2 → 2.1.0

package/dist/react-native/confetti-overlay.js

@@ -20,63 +20,60 @@ export function ConfettiOverlay() {
         color: CONFETTI_COLORS[Math.floor(Math.random() * CONFETTI_COLORS.length)],
         size: 6 + Math.random() * 8,
         startRotation: Math.random() * 360,
-        driftX: (Math.random() > 0.5 ? 1 : -1) * Math.random() * 40,
+        // Per-piece swirl: amplitude, frequency (full oscillations), phase.
+        swirlAmp: 20 + Math.random() * 40,
+        swirlFreq: 1 + Math.random() * 1.5,
+        swirlPhase: Math.random() * Math.PI * 2,
     })), 
     // width captured once on mount; intentional stable dep
     // eslint-disable-next-line react-hooks/exhaustive-deps
     []);
     const anims = useRef(pieces.map(() => ({
-        translateY: new Animated.Value(-20),
-        opacity: new Animated.Value(1),
-        rotate: new Animated.Value(0),
-        translateX: new Animated.Value(0),
+        progress: new Animated.Value(0),
     }))).current;
     useEffect(() => {
         const animations = pieces.map((piece, i) => {
             const anim = anims[i];
-            anim.translateY.setValue(-20);
-            anim.opacity.setValue(1);
-            anim.rotate.setValue(0);
-            anim.translateX.setValue(0);
+            anim.progress.setValue(0);
             return Animated.sequence([
                 Animated.delay(piece.delay),
-                Animated.parallel([
-                    Animated.timing(anim.translateY, {
-                        toValue: height + 20,
-                        duration: piece.duration,
-                        useNativeDriver: true,
-                    }),
-                    Animated.timing(anim.opacity, {
-                        toValue: 0,
-                        duration: piece.duration,
-                        useNativeDriver: true,
-                    }),
-                    Animated.timing(anim.rotate, {
-                        toValue: 720,
-                        duration: piece.duration,
-                        useNativeDriver: true,
-                    }),
-                    Animated.timing(anim.translateX, {
-                        toValue: piece.driftX,
-                        duration: piece.duration,
-                        useNativeDriver: true,
-                    }),
-                ]),
+                Animated.timing(anim.progress, {
+                    toValue: 1,
+                    duration: piece.duration,
+                    useNativeDriver: true,
+                }),
             ]);
         });
         const composite = Animated.parallel(animations);
         composite.start();
         return () => composite.stop();
     }, [pieces, anims, height]);
+    // Sample the sine curve at fixed progress points to build an interpolation
+    // that drives horizontal swirl on the native driver.
+    const SAMPLE_COUNT = 21;
+    const samplePoints = Array.from({ length: SAMPLE_COUNT }, (_, k) => k / (SAMPLE_COUNT - 1));
     return (_jsx(View, { style: [StyleSheet.absoluteFill, styles.container], pointerEvents: "none", children: pieces.map((piece, i) => {
             const anim = anims[i];
-            const rotate = anim.rotate.interpolate({
-                inputRange: [0, 720],
+            const translateY = anim.progress.interpolate({
+                inputRange: [0, 1],
+                outputRange: [-20, height + 20],
+            });
+            const rotate = anim.progress.interpolate({
+                inputRange: [0, 1],
                 outputRange: [
                     `${piece.startRotation}deg`,
                     `${piece.startRotation + 720}deg`,
                 ],
             });
+            const opacity = anim.progress.interpolate({
+                inputRange: [0, 0.5, 1],
+                outputRange: [1, 1, 0],
+            });
+            const translateX = anim.progress.interpolate({
+                inputRange: samplePoints,
+                outputRange: samplePoints.map((t) => Math.sin(t * piece.swirlFreq * Math.PI * 2 + piece.swirlPhase) *
+                    piece.swirlAmp),
+            });
             return (_jsx(Animated.View, { style: [
                     styles.piece,
                     {
@@ -84,10 +81,10 @@ export function ConfettiOverlay() {
                         width: piece.size,
                         height: piece.size * 0.6,
                         backgroundColor: piece.color,
-                        opacity: anim.opacity,
+                        opacity,
                         transform: [
-                            { translateY: anim.translateY },
-                            { translateX: anim.translateX },
+                            { translateY },
+                            { translateX },
                             { rotate },
                         ],
                     },

package/dist/react-native/index.d.ts

@@ -7,7 +7,7 @@ import { hexToRgba } from "./use-snap-palette.js";
 export type { JsonValue, SnapPage, SnapActionHandlers } from "./types.js";
 export { useSnapTheme, hexToRgba };
 export type { SnapNativeColors };
-export declare function SnapCard({ snap, handlers, loading, appearance, colors, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, }: {
+export declare function SnapCard({ snap, handlers, loading, appearance, colors, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -25,4 +25,6 @@ export declare function SnapCard({ snap, handlers, loading, appearance, colors,
     actionError?: string | null;
     /** When true, renders without card frame (no border, background, or padding). */
     plain?: boolean;
+    /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+    loadingOverlay?: ReactNode;
 }): import("react").JSX.Element;

package/dist/react-native/index.js

@@ -7,9 +7,9 @@ import { SnapCardV2 } from "./v2/snap-view.js";
 // ─── Re-exports ───────────────────────────────────────
 export { useSnapTheme, hexToRgba };
 // ─── SnapCard (version-switching) ─────────────────────
-export function SnapCard({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, }) {
+export function SnapCard({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, loadingOverlay, }) {
     if (snap.version === SPEC_VERSION_2) {
-        return (_jsx(SnapCardV2, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, colors: colors, borderRadius: borderRadius, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, plain: plain }));
+        return (_jsx(SnapCardV2, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, colors: colors, borderRadius: borderRadius, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, plain: plain, loadingOverlay: loadingOverlay }));
     }
-    return (_jsx(SnapCardV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, colors: colors, borderRadius: borderRadius, actionError: actionError, plain: plain }));
+    return (_jsx(SnapCardV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, colors: colors, borderRadius: borderRadius, actionError: actionError, plain: plain, loadingOverlay: loadingOverlay }));
 }

package/dist/react-native/snap-view-core.d.ts

@@ -1,11 +1,21 @@
+import { type ReactNode } from "react";
 import type { SnapPage, SnapActionHandlers } from "./types.js";
 export declare function applyStatePaths(model: Record<string, unknown>, changes: {
     path: string;
     value: unknown;
 }[] | Record<string, unknown>): void;
 export declare function resolveAccentHex(accent: string | undefined, appearance: "light" | "dark"): string;
-export declare function SnapViewCoreInner({ snap, handlers, loading, }: {
+export declare function SnapViewCoreInner({ snap, handlers, loading, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
+    /**
+     * Custom content rendered while `loading` is true. When `undefined` (default)
+     * the built-in ActivityIndicator overlay is used. Pass `null` to render nothing.
+     */
+    loadingOverlay?: ReactNode;
+}): import("react").JSX.Element;
+export declare function SnapLoadingOverlay({ appearance, accentHex, }: {
+    appearance: "light" | "dark";
+    accentHex: string;
 }): import("react").JSX.Element;

package/dist/react-native/snap-view-core.js

@@ -1,8 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { snapJsonRenderCatalog } from "@farcaster/snap/ui";
 import { SnapCatalogView } from "./catalog-renderer.js";
+import { ConfettiOverlay } from "./confetti-overlay.js";
 import { useSnapTheme } from "./theme.js";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
 import { ActivityIndicator, StyleSheet, View } from "react-native";
 import { DEFAULT_THEME_ACCENT, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, } from "@farcaster/snap";
 // ─── Shared helpers ──────────────────────────────────
@@ -45,7 +46,7 @@ export function resolveAccentHex(accent, appearance) {
     return map[name];
 }
 // ─── Core rendering component (no validation) ────────
-export function SnapViewCoreInner({ snap, handlers, loading = false, }) {
+export function SnapViewCoreInner({ snap, handlers, loading = false, loadingOverlay, }) {
     const { mode } = useSnapTheme();
     const spec = snap.ui;
     const accentHex = resolveAccentHex(snap.theme?.accent, mode);
@@ -79,6 +80,12 @@ export function SnapViewCoreInner({ snap, handlers, loading = false, }) {
     useEffect(() => {
         setPageKey((k) => k + 1);
     }, [spec]);
+    const showConfetti = snap.effects?.includes("confetti") ?? false;
+    const [confettiKey, setConfettiKey] = useState(0);
+    useEffect(() => {
+        if (showConfetti)
+            setConfettiKey((k) => k + 1);
+    }, [showConfetti, snap]);
     const handlersRef = useRef(handlers);
     handlersRef.current = handlers;
     const handleAction = useCallback((name, params) => {
@@ -134,14 +141,23 @@ export function SnapViewCoreInner({ snap, handlers, loading = false, }) {
                 break;
         }
     }, []);
-    return (_jsxs(View, { style: styles.container, children: [loading ? (_jsx(View, { style: [
-                    styles.overlay,
-                    {
-                        backgroundColor: mode === "dark" ? "rgba(0,0,0,0.1)" : "rgba(255,255,255,0.2)",
-                    },
-                ], children: _jsx(ActivityIndicator, { size: "large", color: accentHex }) })) : null, _jsx(SnapCatalogView, { spec: spec, state: initialState, loading: false, onStateChange: (changes) => {
+    return (_jsxs(View, { style: styles.container, children: [loading
+                ? loadingOverlay === undefined
+                    ? (_jsx(SnapLoadingOverlay, { appearance: mode, accentHex: accentHex }))
+                    : loadingOverlay
+                : null, _jsx(SnapCatalogView, { spec: spec, state: initialState, loading: false, onStateChange: (changes) => {
                     applyStatePaths(stateRef.current, changes);
-                }, onAction: handleAction }, pageKey)] }));
+                }, onAction: handleAction }, pageKey), showConfetti && _jsx(ConfettiOverlay, {}, confettiKey)] }));
+}
+export function SnapLoadingOverlay({ appearance, accentHex, }) {
+    return (_jsx(View, { style: [
+            styles.overlay,
+            {
+                backgroundColor: appearance === "dark"
+                    ? "rgba(0,0,0,0.1)"
+                    : "rgba(255,255,255,0.2)",
+            },
+        ], children: _jsx(ActivityIndicator, { size: "large", color: accentHex }) }));
 }
 const styles = StyleSheet.create({
     container: {

package/dist/react-native/v1/snap-view.d.ts

@@ -1,18 +1,22 @@
+import { type ReactNode } from "react";
 import { type SnapNativeColors } from "../theme.js";
 import type { SnapPage, SnapActionHandlers } from "../types.js";
-export declare function SnapViewV1Inner({ snap, handlers, loading, }: {
+export declare function SnapViewV1Inner({ snap, handlers, loading, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
+    loadingOverlay?: ReactNode;
 }): import("react").JSX.Element;
-export declare function SnapViewV1({ snap, handlers, loading, appearance, colors, }: {
+export declare function SnapViewV1({ snap, handlers, loading, appearance, colors, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
     appearance?: "light" | "dark";
     colors?: Partial<SnapNativeColors>;
+    /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+    loadingOverlay?: ReactNode;
 }): import("react").JSX.Element;
-export declare function SnapCardV1({ snap, handlers, loading, appearance, colors, borderRadius, actionError, plain, }: {
+export declare function SnapCardV1({ snap, handlers, loading, appearance, colors, borderRadius, actionError, plain, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -21,4 +25,6 @@ export declare function SnapCardV1({ snap, handlers, loading, appearance, colors
     borderRadius?: number;
     actionError?: string | null;
     plain?: boolean;
+    /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+    loadingOverlay?: ReactNode;
 }): import("react").JSX.Element;

package/dist/react-native/v1/snap-view.js

@@ -2,18 +2,19 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { useEffect, useState } from "react";
 import { View, Text, StyleSheet, Pressable } from "react-native";
 import { SnapThemeProvider, useSnapTheme } from "../theme.js";
-import { SnapViewCoreInner } from "../snap-view-core.js";
+import { SnapLoadingOverlay, SnapViewCoreInner, resolveAccentHex, } from "../snap-view-core.js";
 const SNAP_MAX_HEIGHT = 500;
 // ─── SnapViewV1 (no validation) ──────────────────────
-export function SnapViewV1Inner({ snap, handlers, loading = false, }) {
-    return (_jsx(SnapViewCoreInner, { snap: snap, handlers: handlers, loading: loading }));
+export function SnapViewV1Inner({ snap, handlers, loading = false, loadingOverlay, }) {
+    return (_jsx(SnapViewCoreInner, { snap: snap, handlers: handlers, loading: loading, loadingOverlay: loadingOverlay }));
 }
-export function SnapViewV1({ snap, handlers, loading = false, appearance = "dark", colors, }) {
-    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapViewV1Inner, { snap: snap, handlers: handlers, loading: loading }) }));
+export function SnapViewV1({ snap, handlers, loading = false, appearance = "dark", colors, loadingOverlay, }) {
+    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapViewV1Inner, { snap: snap, handlers: handlers, loading: loading, loadingOverlay: loadingOverlay }) }));
 }
 // ─── SnapCardV1 (card frame with expandable clipping) ──
-function SnapCardV1Inner({ snap, handlers, loading = false, borderRadius, actionError, appearance, plain, }) {
-    const { colors } = useSnapTheme();
+function SnapCardV1Inner({ snap, handlers, loading = false, borderRadius, actionError, appearance, plain, loadingOverlay, }) {
+    const { colors, mode } = useSnapTheme();
+    const accentHex = resolveAccentHex(snap.theme?.accent, mode);
     const [contentHeight, setContentHeight] = useState(0);
     const [isExpanded, setIsExpanded] = useState(false);
     useEffect(() => {
@@ -22,35 +23,36 @@ function SnapCardV1Inner({ snap, handlers, loading = false, borderRadius, action
     }, [snap]);
     const isExpandable = contentHeight > SNAP_MAX_HEIGHT + 1;
     const isClipped = isExpandable && !isExpanded;
-    return (_jsxs(_Fragment, { children: [_jsx(View, { style: cardStyles.frameRing, children: _jsxs(View, { style: [
-                        plain ? undefined : cardStyles.card,
-                        plain ? undefined : {
-                            borderRadius,
-                            borderColor: colors.border,
-                            backgroundColor: colors.surface,
-                        },
-                    ], children: [_jsx(View, { style: isClipped ? { maxHeight: SNAP_MAX_HEIGHT, overflow: "hidden" } : undefined, children: _jsx(View, { collapsable: false, onLayout: (event) => {
-                                    const nextHeight = Math.round(event.nativeEvent.layout.height);
-                                    setContentHeight((currentHeight) => isClipped
-                                        ? Math.max(currentHeight, nextHeight)
-                                        : currentHeight === nextHeight
-                                            ? currentHeight
-                                            : nextHeight);
-                                }, style: plain ? undefined : cardStyles.body, children: _jsx(SnapViewV1Inner, { snap: snap, handlers: handlers, loading: loading }) }) }), isExpandable ? (_jsx(View, { style: [
-                                cardStyles.expandRow,
-                                plain
-                                    ? cardStyles.expandRowPlain
-                                    : { borderTopColor: colors.border },
-                            ], children: _jsx(Pressable, { style: ({ pressed }) => [
-                                    cardStyles.expandButton,
-                                    {
-                                        backgroundColor: pressed
-                                            ? colors.mutedHover
-                                            : colors.muted,
-                                    },
-                                ], onPress: () => {
-                                    setIsExpanded((value) => !value);
-                                }, children: _jsx(Text, { style: [cardStyles.expandButtonText, { color: colors.text }], children: isExpanded ? "Show less" : "Show more" }) }) })) : null] }) }), actionError && (_jsx(Text, { style: [
+    const isDark = mode === "dark";
+    const pillBg = isDark ? "rgba(40,40,40,0.92)" : "rgba(255,255,255,0.92)";
+    const pillBgPressed = isDark ? "rgba(60,60,60,0.95)" : "rgba(240,240,240,0.95)";
+    return (_jsxs(_Fragment, { children: [_jsxs(View, { style: cardStyles.frameRing, children: [_jsxs(View, { style: [
+                            plain ? undefined : cardStyles.card,
+                            plain ? undefined : {
+                                borderRadius,
+                                borderColor: colors.border,
+                                backgroundColor: colors.surface,
+                            },
+                        ], children: [_jsx(View, { style: isClipped ? { maxHeight: SNAP_MAX_HEIGHT, overflow: "hidden" } : undefined, children: _jsx(View, { collapsable: false, onLayout: (event) => {
+                                        const nextHeight = Math.round(event.nativeEvent.layout.height);
+                                        setContentHeight((currentHeight) => isClipped
+                                            ? Math.max(currentHeight, nextHeight)
+                                            : currentHeight === nextHeight
+                                                ? currentHeight
+                                                : nextHeight);
+                                    }, style: plain ? undefined : cardStyles.body, children: _jsx(SnapViewV1Inner, { snap: snap, handlers: handlers, loading: loading, loadingOverlay: null }) }) }), loading
+                                ? loadingOverlay === undefined
+                                    ? _jsx(SnapLoadingOverlay, { appearance: mode, accentHex: accentHex })
+                                    : loadingOverlay
+                                : null] }), isExpandable ? (_jsx(View, { pointerEvents: "box-none", style: cardStyles.expandFloat, children: _jsx(Pressable, { style: ({ pressed }) => [
+                                cardStyles.expandButton,
+                                {
+                                    backgroundColor: pressed ? pillBgPressed : pillBg,
+                                    borderColor: colors.border,
+                                },
+                            ], onPress: () => {
+                                setIsExpanded((value) => !value);
+                            }, children: _jsx(Text, { style: [cardStyles.expandButtonText, { color: colors.text }], children: isExpanded ? "Show less" : "Show more" }) }) })) : null] }), actionError && (_jsx(Text, { style: [
                     cardStyles.actionError,
                     {
                         color: appearance === "dark"
@@ -59,37 +61,34 @@ function SnapCardV1Inner({ snap, handlers, loading = false, borderRadius, action
                     },
                 ], children: actionError }))] }));
 }
-export function SnapCardV1({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, actionError, plain = false, }) {
-    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapCardV1Inner, { snap: snap, handlers: handlers, loading: loading, borderRadius: borderRadius, actionError: actionError, appearance: appearance, plain: plain }) }));
+export function SnapCardV1({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, actionError, plain = false, loadingOverlay, }) {
+    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapCardV1Inner, { snap: snap, handlers: handlers, loading: loading, borderRadius: borderRadius, actionError: actionError, appearance: appearance, plain: plain, loadingOverlay: loadingOverlay }) }));
 }
 const cardStyles = StyleSheet.create({
     frameRing: { alignSelf: "stretch" },
     card: { overflow: "hidden", borderWidth: 1, minHeight: 120 },
     body: { paddingHorizontal: 16, paddingVertical: 16 },
-    expandRow: {
+    expandFloat: {
+        position: "absolute",
+        left: 0,
+        right: 0,
+        bottom: -14,
+        height: 28,
         alignItems: "center",
-        paddingHorizontal: 16,
-        paddingTop: 10,
-        paddingBottom: 12,
-        borderTopWidth: StyleSheet.hairlineWidth,
-    },
-    expandRowPlain: {
-        paddingHorizontal: 0,
-        paddingTop: 8,
-        paddingBottom: 0,
-        borderTopWidth: 0,
+        justifyContent: "center",
     },
     expandButton: {
         minWidth: 92,
         alignItems: "center",
         justifyContent: "center",
         borderRadius: 9999,
+        borderWidth: 1,
         paddingHorizontal: 10,
-        paddingVertical: 6,
+        paddingVertical: 4,
     },
     expandButtonText: {
-        fontSize: 13,
-        lineHeight: 18,
+        fontSize: 12,
+        lineHeight: 16,
         fontWeight: "600",
     },
     actionError: { paddingHorizontal: 12, paddingVertical: 8, fontSize: 13 },

package/dist/react-native/v2/snap-view.d.ts

@@ -2,14 +2,15 @@ import type { ReactNode } from "react";
 import { type SnapNativeColors } from "../theme.js";
 import { type ValidationResult } from "@farcaster/snap";
 import type { SnapPage, SnapActionHandlers } from "../types.js";
-export declare function SnapViewV2Inner({ snap, handlers, loading, onValidationError, validationErrorFallback, }: {
+export declare function SnapViewV2Inner({ snap, handlers, loading, onValidationError, validationErrorFallback, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
     onValidationError?: (result: ValidationResult) => void;
     validationErrorFallback?: ReactNode;
+    loadingOverlay?: ReactNode;
 }): import("react").JSX.Element;
-export declare function SnapViewV2({ snap, handlers, loading, appearance, colors, onValidationError, validationErrorFallback, }: {
+export declare function SnapViewV2({ snap, handlers, loading, appearance, colors, onValidationError, validationErrorFallback, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -17,8 +18,10 @@ export declare function SnapViewV2({ snap, handlers, loading, appearance, colors
     colors?: Partial<SnapNativeColors>;
     onValidationError?: (result: ValidationResult) => void;
     validationErrorFallback?: ReactNode;
+    /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+    loadingOverlay?: ReactNode;
 }): import("react").JSX.Element;
-export declare function SnapCardV2({ snap, handlers, loading, appearance, colors, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, }: {
+export declare function SnapCardV2({ snap, handlers, loading, appearance, colors, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -30,4 +33,6 @@ export declare function SnapCardV2({ snap, handlers, loading, appearance, colors
     validationErrorFallback?: ReactNode;
     actionError?: string | null;
     plain?: boolean;
+    /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+    loadingOverlay?: ReactNode;
 }): import("react").JSX.Element;

package/dist/react-native/v2/snap-view.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useMemo, useState } from "react";
-import { Platform, StyleSheet, Text, View } from "react-native";
+import { Platform, Pressable, StyleSheet, Text, View } from "react-native";
 import { SnapThemeProvider, useSnapTheme } from "../theme.js";
-import { SnapViewCoreInner } from "../snap-view-core.js";
+import { SnapLoadingOverlay, SnapViewCoreInner, resolveAccentHex, } from "../snap-view-core.js";
 import { validateSnapResponse, } from "@farcaster/snap";
 // ─── Constants ───────────────────────────────────────
 const SNAP_MAX_HEIGHT = 500;
@@ -24,7 +24,7 @@ const fallbackStyles = StyleSheet.create({
     },
 });
 // ─── SnapViewV2 (with validation) ────────────────────
-export function SnapViewV2Inner({ snap, handlers, loading = false, onValidationError, validationErrorFallback, }) {
+export function SnapViewV2Inner({ snap, handlers, loading = false, onValidationError, validationErrorFallback, loadingOverlay, }) {
     const validation = useMemo(() => validateSnapResponse(snap), [snap]);
     const valid = validation.valid;
     const validationMessage = validation.issues[0]?.message;
@@ -44,29 +44,73 @@ export function SnapViewV2Inner({ snap, handlers, loading = false, onValidationE
             return null;
         return (_jsx(_Fragment, { children: validationErrorFallback ?? _jsx(SnapValidationFallback, { message: validationMessage }) }));
     }
-    return (_jsx(SnapViewCoreInner, { snap: snap, handlers: handlers, loading: loading }));
+    return (_jsx(SnapViewCoreInner, { snap: snap, handlers: handlers, loading: loading, loadingOverlay: loadingOverlay }));
 }
-export function SnapViewV2({ snap, handlers, loading = false, appearance = "dark", colors, onValidationError, validationErrorFallback, }) {
-    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapViewV2Inner, { snap: snap, handlers: handlers, loading: loading, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback }) }));
+export function SnapViewV2({ snap, handlers, loading = false, appearance = "dark", colors, onValidationError, validationErrorFallback, loadingOverlay, }) {
+    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapViewV2Inner, { snap: snap, handlers: handlers, loading: loading, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, loadingOverlay: loadingOverlay }) }));
 }
 // ─── SnapCardV2 (card frame + height limits) ─────────
-function SnapCardV2Inner({ snap, handlers, loading, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, appearance, plain, }) {
-    const { colors } = useSnapTheme();
+function SnapCardV2Inner({ snap, handlers, loading, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, appearance, plain, loadingOverlay, }) {
+    const { colors, mode } = useSnapTheme();
+    const accentHex = resolveAccentHex(snap.theme?.accent, mode);
     const [contentHeight, setContentHeight] = useState(0);
-    const content = (_jsx(SnapViewV2Inner, { snap: snap, handlers: handlers, loading: loading, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback }));
+    const [isExpanded, setIsExpanded] = useState(false);
+    useEffect(() => {
+        setIsExpanded(false);
+        setContentHeight(0);
+    }, [snap]);
+    const isExpandable = !showOverflowWarning && contentHeight > SNAP_MAX_HEIGHT + 1;
+    const isClipped = isExpandable && !isExpanded;
+    const content = (_jsx(SnapViewV2Inner, { snap: snap, handlers: handlers, loading: loading, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, loadingOverlay: null }));
     if (plain) {
-        return content;
+        return (_jsxs(_Fragment, { children: [_jsx(View, { style: isClipped ? { maxHeight: SNAP_MAX_HEIGHT, overflow: "hidden" } : undefined, children: _jsx(View, { collapsable: false, onLayout: (e) => {
+                            const nextHeight = Math.round(e.nativeEvent.layout.height);
+                            setContentHeight((current) => isClipped
+                                ? Math.max(current, nextHeight)
+                                : current === nextHeight
+                                    ? current
+                                    : nextHeight);
+                        }, children: content }) }), loading
+                    ? loadingOverlay === undefined
+                        ? _jsx(SnapLoadingOverlay, { appearance: mode, accentHex: accentHex })
+                        : loadingOverlay
+                    : null, isExpandable ? (_jsx(View, { style: [cardStyles.expandRow, cardStyles.expandRowPlain], children: _jsx(Pressable, { style: ({ pressed }) => [
+                            cardStyles.expandButton,
+                            {
+                                backgroundColor: pressed ? colors.mutedHover : colors.muted,
+                            },
+                        ], onPress: () => setIsExpanded((value) => !value), children: _jsx(Text, { style: [cardStyles.expandButtonText, { color: colors.text }], children: isExpanded ? "Show less" : "Show more" }) }) })) : null] }));
     }
     const overflowAmount = showOverflowWarning ? contentHeight - SNAP_MAX_HEIGHT : 0;
-    return (_jsxs(_Fragment, { children: [_jsxs(View, { style: {
-                    borderRadius,
-                    borderWidth: 1,
-                    borderColor: colors.border,
-                    backgroundColor: colors.surface,
-                    maxHeight: showOverflowWarning ? undefined : SNAP_MAX_HEIGHT,
-                    overflow: "hidden",
-                    minHeight: 120,
-                }, children: [_jsx(View, { collapsable: false, onLayout: (e) => setContentHeight(Math.round(e.nativeEvent.layout.height)), style: { paddingHorizontal: 16, paddingVertical: 16 }, children: content }), showOverflowWarning && contentHeight > SNAP_MAX_HEIGHT && (_jsxs(View, { style: { position: "absolute", top: SNAP_MAX_HEIGHT, left: 0, right: 0, height: overflowAmount, zIndex: 10, pointerEvents: "none" }, children: [_jsx(View, { style: { height: 1, borderTopWidth: 1, borderStyle: "dashed", borderColor: "rgba(255,100,100,0.6)" } }), _jsx(View, { style: { position: "absolute", top: -10, right: 4, backgroundColor: "rgba(0,0,0,0.7)", paddingHorizontal: 4, paddingVertical: 1, borderRadius: 3 }, children: _jsxs(Text, { style: { fontSize: 10, color: "rgba(255,100,100,0.7)", fontFamily: Platform.select({ ios: "Menlo", default: "monospace" }) }, children: [SNAP_MAX_HEIGHT, "px"] }) }), _jsx(View, { style: { flex: 1, backgroundColor: "rgba(255,50,50,0.15)" } })] }))] }), actionError && (_jsx(Text, { style: {
+    const isDark = mode === "dark";
+    const pillBg = isDark ? "rgba(40,40,40,0.92)" : "rgba(255,255,255,0.92)";
+    const pillBgPressed = isDark ? "rgba(60,60,60,0.95)" : "rgba(240,240,240,0.95)";
+    return (_jsxs(_Fragment, { children: [_jsxs(View, { style: { position: "relative" }, children: [_jsxs(View, { style: {
+                            borderRadius,
+                            borderWidth: 1,
+                            borderColor: colors.border,
+                            backgroundColor: colors.surface,
+                            maxHeight: showOverflowWarning ? undefined : isClipped ? SNAP_MAX_HEIGHT : undefined,
+                            overflow: "hidden",
+                            minHeight: 120,
+                        }, children: [_jsx(View, { collapsable: false, onLayout: (e) => {
+                                    const nextHeight = Math.round(e.nativeEvent.layout.height);
+                                    setContentHeight((current) => isClipped
+                                        ? Math.max(current, nextHeight)
+                                        : current === nextHeight
+                                            ? current
+                                            : nextHeight);
+                                }, style: { paddingHorizontal: 16, paddingVertical: 16 }, children: content }), showOverflowWarning && contentHeight > SNAP_MAX_HEIGHT && (_jsxs(View, { style: { position: "absolute", top: SNAP_MAX_HEIGHT, left: 0, right: 0, height: overflowAmount, zIndex: 10, pointerEvents: "none" }, children: [_jsx(View, { style: { height: 1, borderTopWidth: 1, borderStyle: "dashed", borderColor: "rgba(255,100,100,0.6)" } }), _jsx(View, { style: { position: "absolute", top: -10, right: 4, backgroundColor: "rgba(0,0,0,0.7)", paddingHorizontal: 4, paddingVertical: 1, borderRadius: 3 }, children: _jsxs(Text, { style: { fontSize: 10, color: "rgba(255,100,100,0.7)", fontFamily: Platform.select({ ios: "Menlo", default: "monospace" }) }, children: [SNAP_MAX_HEIGHT, "px"] }) }), _jsx(View, { style: { flex: 1, backgroundColor: "rgba(255,50,50,0.15)" } })] })), loading
+                                ? loadingOverlay === undefined
+                                    ? _jsx(SnapLoadingOverlay, { appearance: mode, accentHex: accentHex })
+                                    : loadingOverlay
+                                : null] }), isExpandable ? (_jsx(View, { pointerEvents: "box-none", style: cardStyles.expandFloat, children: _jsx(Pressable, { style: ({ pressed }) => [
+                                cardStyles.expandButton,
+                                {
+                                    backgroundColor: pressed ? pillBgPressed : pillBg,
+                                    borderColor: colors.border,
+                                },
+                            ], onPress: () => setIsExpanded((value) => !value), children: _jsx(Text, { style: [cardStyles.expandButtonText, { color: colors.text }], children: isExpanded ? "Show less" : "Show more" }) }) })) : null] }), actionError && (_jsx(Text, { style: {
                     paddingHorizontal: 12,
                     paddingVertical: 8,
                     fontSize: 13,
@@ -75,14 +119,41 @@ function SnapCardV2Inner({ snap, handlers, loading, borderRadius, showOverflowWa
                         : "rgba(200,0,0,0.8)",
                 }, children: actionError }))] }));
 }
-export function SnapCardV2({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, }) {
-    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapCardV2Inner, { snap: snap, handlers: handlers, loading: loading, borderRadius: borderRadius, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, appearance: appearance, plain: plain }) }));
+export function SnapCardV2({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, loadingOverlay, }) {
+    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapCardV2Inner, { snap: snap, handlers: handlers, loading: loading, borderRadius: borderRadius, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, appearance: appearance, plain: plain, loadingOverlay: loadingOverlay }) }));
 }
 const cardStyles = StyleSheet.create({
     frameRing: { alignSelf: "stretch" },
     card: { borderWidth: 1, minHeight: 120, overflow: "hidden" },
     body: { paddingHorizontal: 16, paddingVertical: 16 },
     actionError: { paddingHorizontal: 12, paddingVertical: 8, fontSize: 13 },
+    expandFloat: {
+        position: "absolute",
+        left: 0,
+        right: 0,
+        bottom: -14,
+        height: 28,
+        alignItems: "center",
+        justifyContent: "center",
+    },
+    expandRowPlain: {
+        paddingTop: 8,
+        alignItems: "center",
+    },
+    expandButton: {
+        minWidth: 92,
+        alignItems: "center",
+        justifyContent: "center",
+        borderRadius: 9999,
+        borderWidth: 1,
+        paddingHorizontal: 10,
+        paddingVertical: 4,
+    },
+    expandButtonText: {
+        fontSize: 12,
+        lineHeight: 16,
+        fontWeight: "600",
+    },
     warningOverlay: {
         position: "absolute",
         top: SNAP_MAX_HEIGHT,

package/dist/ui/catalog.js

@@ -50,7 +50,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
         },
         item: {
             props: itemProps,
-            description: "Content row with title and optional description. Children render in the actions slot (right side) — use badge, button, or text elements.",
+            description: "Content row with title and optional description. Children render in the actions slot (right side) — badge, button, and icon elements are all valid. The item itself is not interactive, so avoid navigation-style icons (`chevron-right`, `arrow-right`, `external-link`) that imply the row navigates.",
         },
         item_group: {
             props: itemGroupProps,
@@ -90,7 +90,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
         },
         cell_grid: {
             props: cellGridProps,
-            description: "Cell grid — sparse colored cells on a rows×cols grid. Optional gap and selection mode (taps write to inputs[name]).",
+            description: "Cell grid — sparse colored cells on a rows×cols grid. Two interaction modes: leave select 'off' and bind on.press to fire an action per cell press (inputs[name] is the pressed 'row,col' before the action runs); or set select 'single'/'multiple' for press-to-select with a visual ring (no auto-fire — pair with a separate submit button). on.press is ignored when select is on.",
         },
     },
     actions: {