@farcaster/snap 2.0.1 → 2.0.3

package/dist/react/components/action-button.js

@@ -24,18 +24,21 @@ export function SnapActionButton({ element, emit, }) {
     const [hovered, setHovered] = useState(false);
     const Icon = iconName ? ICON_MAP[iconName] : undefined;
     const showExternalIcon = isExternalLinkAction(element.on);
-    const style = isPrimary
-        ? {
-            backgroundColor: hovered ? colors.accentHover : colors.accent,
-            color: colors.accentFg,
-            borderColor: "transparent",
-        }
-        : {
-            backgroundColor: hovered
-                ? `color-mix(in srgb, ${colors.accent} 15%, transparent)`
-                : colors.muted,
-            color: colors.text,
-            borderColor: "transparent",
-        };
+    const style = {
+        cursor: "pointer",
+        ...(isPrimary
+            ? {
+                backgroundColor: hovered ? colors.accentHover : colors.accent,
+                color: colors.accentFg,
+                borderColor: "transparent",
+            }
+            : {
+                backgroundColor: hovered
+                    ? `color-mix(in srgb, ${colors.accent} 15%, transparent)`
+                    : colors.muted,
+                color: colors.text,
+                borderColor: "transparent",
+            }),
+    };
     return (_jsx("div", { className: "w-full min-w-0 flex-1", children: _jsxs(Button, { type: "button", variant: isPrimary ? "default" : "secondary", className: cn("w-full gap-2"), style: style, onClick: () => emit("press"), onPointerEnter: () => setHovered(true), onPointerLeave: () => setHovered(false), children: [Icon && _jsx(Icon, { size: 16 }), label, showExternalIcon && (_jsx(ExternalLink, { size: 14, style: { opacity: 0.6 } }))] }) }));
 }

package/dist/react/index.d.ts

@@ -42,7 +42,7 @@ export type SnapActionHandlers = {
         buyToken?: string;
     }) => void;
 };
-export declare function SnapCard({ snap, handlers, loading, appearance, maxWidth, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, }: {
+export declare function SnapCard({ snap, handlers, loading, appearance, maxWidth, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -56,4 +56,6 @@ export declare function SnapCard({ snap, handlers, loading, appearance, maxWidth
     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-runtime").JSX.Element;

package/dist/react/index.js

@@ -4,9 +4,9 @@ import { SPEC_VERSION_2 } from "../constants.js";
 import { SnapCardV1 } from "./v1/snap-view.js";
 import { SnapCardV2 } from "./v2/snap-view.js";
 // ─── SnapCard ────────────────────────────────────────
-export function SnapCard({ snap, handlers, loading = false, appearance = "dark", maxWidth = 480, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, }) {
+export function SnapCard({ snap, handlers, loading = false, appearance = "dark", maxWidth = 480, 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, maxWidth: maxWidth, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, plain: plain }));
+        return (_jsx(SnapCardV2, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, maxWidth: maxWidth, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, plain: plain, loadingOverlay: loadingOverlay }));
     }
-    return (_jsx(SnapCardV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, maxWidth: maxWidth, actionError: actionError, plain: plain }));
+    return (_jsx(SnapCardV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, maxWidth: maxWidth, actionError: actionError, plain: plain, loadingOverlay: loadingOverlay }));
 }

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

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

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

@@ -1,5 +1,5 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { snapJsonRenderCatalog } from "../ui/index.js";
 import { SnapCatalogView } from "./catalog-renderer.js";
 import { SnapPreviewAccentProvider } from "./accent-context.js";
@@ -75,7 +75,7 @@ function ConfettiOverlay() {
                     animation: `confettiFall ${duration}s ease-in ${delay}s forwards`,
                 } }, id))), _jsx("style", { children: `@keyframes confettiFall{0%{top:-20px;opacity:1;transform:rotate(0deg) translateX(0)}50%{opacity:1}100%{top:110%;opacity:0;transform:rotate(720deg) translateX(${Math.random() > 0.5 ? "" : "-"}40px)}}` })] }));
 }
-function SnapLoadingOverlay({ appearance, accentHex, active, }) {
+export function SnapLoadingOverlay({ appearance, accentHex, active, }) {
     const isDark = appearance === "dark";
     const tint = isDark ? "rgba(0, 0, 0, 0.1)" : "rgba(255, 255, 255, 0.2)";
     const trackColor = isDark
@@ -130,7 +130,7 @@ const PALETTE = [
 ];
 // ─── SnapViewCore ────────────────────────────────────
 // Shared rendering logic used by both v1 and v2.
-export function SnapViewCore({ snap, handlers, loading = false, appearance = "dark", }) {
+export function SnapViewCore({ snap, handlers, loading = false, appearance = "dark", loadingOverlay, }) {
     const spec = snap.ui;
     const initialState = useMemo(() => spec.state ?? { inputs: {} }, [spec]);
     const stateRef = useRef(initialState);
@@ -177,6 +177,9 @@ export function SnapViewCore({ snap, handlers, loading = false, appearance = "da
             case "open_url":
                 handlers.open_url(String(p.target ?? ""));
                 break;
+            case "open_snap":
+                handlers.open_snap(String(p.target ?? ""));
+                break;
             case "open_mini_app":
                 handlers.open_mini_app(String(p.target ?? ""));
                 break;
@@ -218,7 +221,7 @@ export function SnapViewCore({ snap, handlers, loading = false, appearance = "da
                 break;
         }
     }, [handlers]);
-    return (_jsxs("div", { style: { position: "relative", width: "100%" }, children: [showConfetti && _jsx(ConfettiOverlay, {}), _jsx(SnapLoadingOverlay, { appearance: appearance, accentHex: accentHex, active: loading }), _jsx("div", { style: previewSurfaceStyle, children: _jsx(SnapPreviewAccentProvider, { pageAccent: snap.theme?.accent, appearance: appearance, children: _jsx(SnapCatalogView, { spec: spec, state: initialState, loading: false, onStateChange: (changes) => {
+    return (_jsxs("div", { style: { position: "relative", width: "100%" }, children: [showConfetti && _jsx(ConfettiOverlay, {}), loadingOverlay === undefined ? (_jsx(SnapLoadingOverlay, { appearance: appearance, accentHex: accentHex, active: loading })) : loading ? (_jsx(_Fragment, { children: loadingOverlay })) : null, _jsx("div", { style: previewSurfaceStyle, children: _jsx(SnapPreviewAccentProvider, { pageAccent: snap.theme?.accent, appearance: appearance, children: _jsx(SnapCatalogView, { spec: spec, state: initialState, loading: false, onStateChange: (changes) => {
                             applyStatePaths(stateRef.current, changes);
                         }, onAction: handleAction }, pageKey) }) })] }));
 }

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

@@ -1,11 +1,14 @@
+import { type ReactNode } from "react";
 import type { SnapPage, SnapActionHandlers } from "../index.js";
-export declare function SnapViewV1({ snap, handlers, loading, appearance, }: {
+export declare function SnapViewV1({ snap, handlers, loading, appearance, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
     appearance?: "light" | "dark";
+    /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+    loadingOverlay?: ReactNode;
 }): import("react/jsx-runtime").JSX.Element;
-export declare function SnapCardV1({ snap, handlers, loading, appearance, maxWidth, actionError, plain, }: {
+export declare function SnapCardV1({ snap, handlers, loading, appearance, maxWidth, actionError, plain, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -13,4 +16,6 @@ export declare function SnapCardV1({ snap, handlers, loading, appearance, maxWid
     maxWidth?: number;
     actionError?: string | null;
     plain?: boolean;
+    /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+    loadingOverlay?: ReactNode;
 }): import("react/jsx-runtime").JSX.Element;

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

@@ -1,12 +1,13 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from "react";
-import { SnapViewCore } from "../snap-view-core.js";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { SnapViewCore, SnapLoadingOverlay } from "../snap-view-core.js";
+import { resolveSnapPaletteHex } from "../lib/resolve-palette-hex.js";
 const SNAP_MAX_HEIGHT = 500;
-export function SnapViewV1({ snap, handlers, loading = false, appearance = "dark", }) {
-    return (_jsx(SnapViewCore, { snap: snap, handlers: handlers, loading: loading, appearance: appearance }));
+export function SnapViewV1({ snap, handlers, loading = false, appearance = "dark", loadingOverlay, }) {
+    return (_jsx(SnapViewCore, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, loadingOverlay: loadingOverlay }));
 }
-export function SnapCardV1({ snap, handlers, loading = false, appearance = "dark", maxWidth = 480, actionError, plain = false, }) {
+export function SnapCardV1({ snap, handlers, loading = false, appearance = "dark", maxWidth = 480, actionError, plain = false, loadingOverlay, }) {
     const isDark = appearance === "dark";
     const borderColor = isDark ? "rgba(255,255,255,0.1)" : "rgba(0,0,0,0.1)";
     const surfaceBg = isDark ? "rgba(255,255,255,0.05)" : "rgba(0,0,0,0.02)";
@@ -43,6 +44,7 @@ export function SnapCardV1({ snap, handlers, loading = false, appearance = "dark
         }
     }, [isExpandable]);
     const isClipped = isExpandable && !isExpanded;
+    const accentHex = useMemo(() => resolveSnapPaletteHex(snap.theme?.accent ?? "purple", appearance), [snap.theme?.accent, appearance]);
     return (_jsxs("div", { style: {
             position: "relative",
             width: "100%",
@@ -58,7 +60,7 @@ export function SnapCardV1({ snap, handlers, loading = false, appearance = "dark
                         maxHeight: SNAP_MAX_HEIGHT,
                         overflow: "hidden",
                     }
-                    : undefined, children: _jsx("div", { ref: contentRef, style: plain ? undefined : { padding: 16 }, children: _jsx(SnapViewV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance }) }) }), isExpandable ? (_jsx("div", { style: {
+                    : undefined, children: _jsx("div", { ref: contentRef, style: plain ? undefined : { padding: 16 }, children: _jsx(SnapViewV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, loadingOverlay: null }) }) }), loadingOverlay === undefined ? (_jsx(SnapLoadingOverlay, { appearance: appearance, accentHex: accentHex, active: loading })) : loading ? (_jsx(_Fragment, { children: loadingOverlay })) : null, isExpandable ? (_jsx("div", { style: {
                     display: "flex",
                     justifyContent: "center",
                     padding: plain ? "8px 0 0" : "10px 16px 12px",

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

@@ -1,15 +1,17 @@
 import { type ReactNode } from "react";
 import type { ValidationResult } from "../../validator.js";
 import type { SnapPage, SnapActionHandlers } from "../index.js";
-export declare function SnapViewV2({ snap, handlers, loading, appearance, onValidationError, validationErrorFallback, }: {
+export declare function SnapViewV2({ snap, handlers, loading, appearance, onValidationError, validationErrorFallback, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
     appearance?: "light" | "dark";
     onValidationError?: (result: ValidationResult) => void;
     validationErrorFallback?: ReactNode;
+    /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+    loadingOverlay?: ReactNode;
 }): import("react/jsx-runtime").JSX.Element | null;
-export declare function SnapCardV2({ snap, handlers, loading, appearance, maxWidth, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, }: {
+export declare function SnapCardV2({ snap, handlers, loading, appearance, maxWidth, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, loadingOverlay, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -20,4 +22,6 @@ export declare function SnapCardV2({ snap, handlers, loading, appearance, maxWid
     validationErrorFallback?: ReactNode;
     actionError?: string | null;
     plain?: boolean;
+    /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+    loadingOverlay?: ReactNode;
 }): import("react/jsx-runtime").JSX.Element;

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

@@ -2,7 +2,8 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useMemo } from "react";
 import { validateSnapResponse } from "../../validator.js";
-import { SnapViewCore } from "../snap-view-core.js";
+import { SnapViewCore, SnapLoadingOverlay } from "../snap-view-core.js";
+import { resolveSnapPaletteHex } from "../lib/resolve-palette-hex.js";
 const SNAP_MAX_HEIGHT = 500;
 const SNAP_WARNING_HEIGHT = 700;
 // ─── Default validation error fallback ────────────────
@@ -19,7 +20,7 @@ function SnapValidationFallback({ appearance, message, }) {
         }, children: _jsx("span", { children: message ? `Unable to render snap: ${message}` : "Unable to render snap" }) }));
 }
 // ─── SnapViewV2 ──────────────────────────────────────
-export function SnapViewV2({ snap, handlers, loading = false, appearance = "dark", onValidationError, validationErrorFallback, }) {
+export function SnapViewV2({ snap, handlers, loading = false, appearance = "dark", onValidationError, validationErrorFallback, loadingOverlay, }) {
     const validation = useMemo(() => validateSnapResponse(snap), [snap]);
     const valid = validation.valid;
     const validationMessage = validation.issues[0]?.message;
@@ -39,15 +40,16 @@ export function SnapViewV2({ snap, handlers, loading = false, appearance = "dark
             return null;
         return _jsx(_Fragment, { children: validationErrorFallback ?? _jsx(SnapValidationFallback, { appearance: appearance, message: validationMessage }) });
     }
-    return (_jsx(SnapViewCore, { snap: snap, handlers: handlers, loading: loading, appearance: appearance }));
+    return (_jsx(SnapViewCore, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, loadingOverlay: loadingOverlay }));
 }
 // ─── SnapCardV2 ──────────────────────────────────────
-export function SnapCardV2({ snap, handlers, loading = false, appearance = "dark", maxWidth = 480, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, }) {
+export function SnapCardV2({ snap, handlers, loading = false, appearance = "dark", maxWidth = 480, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, loadingOverlay, }) {
     const maxHeight = showOverflowWarning ? SNAP_WARNING_HEIGHT : SNAP_MAX_HEIGHT;
     const isDark = appearance === "dark";
     const bg = isDark ? "rgba(0,0,0,0.85)" : "rgba(255,255,255,0.9)";
     const borderColor = isDark ? "rgba(255,255,255,0.1)" : "rgba(0,0,0,0.1)";
     const surfaceBg = isDark ? "rgba(255,255,255,0.05)" : "rgba(0,0,0,0.02)";
+    const accentHex = useMemo(() => resolveSnapPaletteHex(snap.theme?.accent ?? "purple", appearance), [snap.theme?.accent, appearance]);
     return (_jsxs(_Fragment, { children: [_jsxs("div", { style: {
                     position: "relative",
                     width: "100%",
@@ -59,7 +61,7 @@ export function SnapCardV2({ snap, handlers, loading = false, appearance = "dark
                         border: `1px solid ${borderColor}`,
                         backgroundColor: surfaceBg,
                     }),
-                }, children: [_jsx("div", { style: plain ? undefined : { padding: 16 }, children: _jsx(SnapViewV2, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback }) }), showOverflowWarning && (_jsxs("div", { style: {
+                }, children: [_jsx("div", { style: plain ? undefined : { padding: 16 }, children: _jsx(SnapViewV2, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, loadingOverlay: null }) }), loadingOverlay === undefined ? (_jsx(SnapLoadingOverlay, { appearance: appearance, accentHex: accentHex, active: loading })) : loading ? (_jsx(_Fragment, { children: loadingOverlay })) : null, showOverflowWarning && (_jsxs("div", { style: {
                             position: "absolute",
                             top: SNAP_MAX_HEIGHT,
                             left: 0,

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

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { snapJsonRenderCatalog } from "@farcaster/snap/ui";
 import { SnapCatalogView } from "./catalog-renderer.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 +45,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);
@@ -92,6 +92,9 @@ export function SnapViewCoreInner({ snap, handlers, loading = false, }) {
             case "open_url":
                 h.open_url(String(p.target ?? ""));
                 break;
+            case "open_snap":
+                h.open_snap(String(p.target ?? ""));
+                break;
             case "open_mini_app":
                 h.open_mini_app(String(p.target ?? ""));
                 break;
@@ -131,15 +134,24 @@ 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)] }));
 }
+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: {
         width: "100%",

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(() => {
@@ -36,7 +37,11 @@ function SnapCardV1Inner({ snap, handlers, loading = false, borderRadius, action
                                         : currentHeight === nextHeight
                                             ? currentHeight
                                             : nextHeight);
-                                }, style: plain ? undefined : cardStyles.body, children: _jsx(SnapViewV1Inner, { snap: snap, handlers: handlers, loading: loading }) }) }), isExpandable ? (_jsx(View, { style: [
+                                }, 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, { style: [
                                 cardStyles.expandRow,
                                 plain
                                     ? cardStyles.expandRowPlain
@@ -59,8 +64,8 @@ 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" },

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

@@ -2,7 +2,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { useEffect, useMemo, useState } from "react";
 import { Platform, 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,18 +44,23 @@ 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 content = (_jsx(SnapViewV2Inner, { snap: snap, handlers: handlers, loading: loading, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, loadingOverlay: null }));
     if (plain) {
-        return content;
+        return (_jsxs(_Fragment, { children: [content, loading
+                    ? loadingOverlay === undefined
+                        ? _jsx(SnapLoadingOverlay, { appearance: mode, accentHex: accentHex })
+                        : loadingOverlay
+                    : null] }));
     }
     const overflowAmount = showOverflowWarning ? contentHeight - SNAP_MAX_HEIGHT : 0;
     return (_jsxs(_Fragment, { children: [_jsxs(View, { style: {
@@ -66,7 +71,11 @@ function SnapCardV2Inner({ snap, handlers, loading, borderRadius, showOverflowWa
                     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: {
+                }, 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)" } })] })), loading
+                        ? loadingOverlay === undefined
+                            ? _jsx(SnapLoadingOverlay, { appearance: mode, accentHex: accentHex })
+                            : loadingOverlay
+                        : null] }), actionError && (_jsx(Text, { style: {
                     paddingHorizontal: 12,
                     paddingVertical: 8,
                     fontSize: 13,
@@ -75,8 +84,8 @@ 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" },

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,