@farcaster/snap 1.17.0 → 1.17.2

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, }: {
+export declare function SnapCard({ snap, handlers, loading, appearance, colors, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -21,4 +21,6 @@ export declare function SnapCard({ snap, handlers, loading, appearance, colors,
     onValidationError?: (result: ValidationResult) => void;
     /** Custom fallback rendered when validation fails (v2 only). */
     validationErrorFallback?: ReactNode;
+    /** Server-side action error message to display inline. */
+    actionError?: string | null;
 }): 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, }) {
+export function SnapCard({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, }) {
     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 }));
+        return (_jsx(SnapCardV2, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, colors: colors, borderRadius: borderRadius, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError }));
     }
-    return (_jsx(SnapCardV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, colors: colors, borderRadius: borderRadius }));
+    return (_jsx(SnapCardV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, colors: colors, borderRadius: borderRadius, actionError: actionError }));
 }

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

@@ -12,11 +12,12 @@ export declare function SnapViewV1({ snap, handlers, loading, appearance, colors
     appearance?: "light" | "dark";
     colors?: Partial<SnapNativeColors>;
 }): import("react").JSX.Element;
-export declare function SnapCardV1({ snap, handlers, loading, appearance, colors, borderRadius, }: {
+export declare function SnapCardV1({ snap, handlers, loading, appearance, colors, borderRadius, actionError, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
     appearance?: "light" | "dark";
     colors?: Partial<SnapNativeColors>;
     borderRadius?: number;
+    actionError?: string | null;
 }): import("react").JSX.Element;

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

@@ -1,5 +1,5 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { View, StyleSheet } from "react-native";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { View, Text, StyleSheet } from "react-native";
 import { SnapThemeProvider, useSnapTheme } from "../theme.js";
 import { SnapViewCoreInner } from "../snap-view-core.js";
 // ─── SnapViewV1 (no validation, no height limits) ────
@@ -10,22 +10,30 @@ export function SnapViewV1({ snap, handlers, loading = false, appearance = "dark
     return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapViewV1Inner, { snap: snap, handlers: handlers, loading: loading }) }));
 }
 // ─── SnapCardV1 (card frame, no height limits) ───────
-function SnapCardV1Inner({ snap, handlers, loading = false, borderRadius, }) {
+function SnapCardV1Inner({ snap, handlers, loading = false, borderRadius, actionError, appearance, }) {
     const { colors } = useSnapTheme();
-    return (_jsx(View, { style: cardStyles.frameRing, children: _jsx(View, { style: [
-                cardStyles.card,
-                {
-                    borderRadius,
-                    borderColor: colors.border,
-                    backgroundColor: colors.surface,
-                },
-            ], children: _jsx(View, { style: cardStyles.body, children: _jsx(SnapViewV1Inner, { snap: snap, handlers: handlers, loading: loading }) }) }) }));
+    return (_jsxs(_Fragment, { children: [_jsx(View, { style: cardStyles.frameRing, children: _jsx(View, { style: [
+                        cardStyles.card,
+                        {
+                            borderRadius,
+                            borderColor: colors.border,
+                            backgroundColor: colors.surface,
+                        },
+                    ], children: _jsx(View, { style: cardStyles.body, children: _jsx(SnapViewV1Inner, { snap: snap, handlers: handlers, loading: loading }) }) }) }), actionError && (_jsx(Text, { style: [
+                    cardStyles.actionError,
+                    {
+                        color: appearance === "dark"
+                            ? "rgba(255,100,100,0.9)"
+                            : "rgba(200,0,0,0.8)",
+                    },
+                ], children: actionError }))] }));
 }
-export function SnapCardV1({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, }) {
-    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapCardV1Inner, { snap: snap, handlers: handlers, loading: loading, borderRadius: borderRadius }) }));
+export function SnapCardV1({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, actionError, }) {
+    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapCardV1Inner, { snap: snap, handlers: handlers, loading: loading, borderRadius: borderRadius, actionError: actionError, appearance: appearance }) }));
 }
 const cardStyles = StyleSheet.create({
     frameRing: { alignSelf: "stretch" },
     card: { overflow: "hidden", borderWidth: 1, minHeight: 120 },
     body: { paddingHorizontal: 16, paddingVertical: 16 },
+    actionError: { paddingHorizontal: 12, paddingVertical: 8, fontSize: 13 },
 });

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

@@ -18,7 +18,7 @@ export declare function SnapViewV2({ snap, handlers, loading, appearance, colors
     onValidationError?: (result: ValidationResult) => void;
     validationErrorFallback?: ReactNode;
 }): import("react").JSX.Element;
-export declare function SnapCardV2({ snap, handlers, loading, appearance, colors, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, }: {
+export declare function SnapCardV2({ snap, handlers, loading, appearance, colors, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -28,4 +28,5 @@ export declare function SnapCardV2({ snap, handlers, loading, appearance, colors
     showOverflowWarning?: boolean;
     onValidationError?: (result: ValidationResult) => void;
     validationErrorFallback?: ReactNode;
+    actionError?: string | null;
 }): import("react").JSX.Element;

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

@@ -50,26 +50,34 @@ export function SnapViewV2({ snap, handlers, loading = false, appearance = "dark
     return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapViewV2Inner, { snap: snap, handlers: handlers, loading: loading, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback }) }));
 }
 // ─── SnapCardV2 (card frame + height limits) ─────────
-function SnapCardV2Inner({ snap, handlers, loading, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, }) {
+function SnapCardV2Inner({ snap, handlers, loading, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, appearance, }) {
     const { colors } = useSnapTheme();
     const maxHeight = showOverflowWarning ? SNAP_WARNING_HEIGHT : SNAP_MAX_HEIGHT;
-    return (_jsx(View, { style: cardStyles.frameRing, children: _jsxs(View, { style: [
-                cardStyles.card,
-                {
-                    borderRadius,
-                    maxHeight,
-                    borderColor: colors.border,
-                    backgroundColor: colors.surface,
-                },
-            ], children: [_jsx(View, { style: cardStyles.body, children: _jsx(SnapViewV2Inner, { snap: snap, handlers: handlers, loading: loading, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback }) }), showOverflowWarning && (_jsxs(View, { style: cardStyles.warningOverlay, children: [_jsx(View, { style: cardStyles.warningLine }), _jsx(View, { style: cardStyles.warningLabel, children: _jsxs(Text, { style: cardStyles.warningLabelText, children: [SNAP_MAX_HEIGHT, "px"] }) })] }))] }) }));
+    return (_jsxs(_Fragment, { children: [_jsx(View, { style: cardStyles.frameRing, children: _jsxs(View, { style: [
+                        cardStyles.card,
+                        {
+                            borderRadius,
+                            maxHeight,
+                            borderColor: colors.border,
+                            backgroundColor: colors.surface,
+                        },
+                    ], children: [_jsx(View, { style: cardStyles.body, children: _jsx(SnapViewV2Inner, { snap: snap, handlers: handlers, loading: loading, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback }) }), showOverflowWarning && (_jsxs(View, { style: cardStyles.warningOverlay, children: [_jsx(View, { style: cardStyles.warningLine }), _jsx(View, { style: cardStyles.warningLabel, children: _jsxs(Text, { style: cardStyles.warningLabelText, children: [SNAP_MAX_HEIGHT, "px"] }) })] }))] }) }), actionError && (_jsx(Text, { style: [
+                    cardStyles.actionError,
+                    {
+                        color: appearance === "dark"
+                            ? "rgba(255,100,100,0.9)"
+                            : "rgba(200,0,0,0.8)",
+                    },
+                ], children: actionError }))] }));
 }
-export function SnapCardV2({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, showOverflowWarning = false, onValidationError, validationErrorFallback, }) {
-    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapCardV2Inner, { snap: snap, handlers: handlers, loading: loading, borderRadius: borderRadius, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback }) }));
+export function SnapCardV2({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, }) {
+    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 }) }));
 }
 const cardStyles = StyleSheet.create({
     frameRing: { alignSelf: "stretch" },
     card: { overflow: "hidden", borderWidth: 1, minHeight: 120 },
     body: { paddingHorizontal: 16, paddingVertical: 16 },
+    actionError: { paddingHorizontal: 12, paddingVertical: 8, fontSize: 13 },
     warningOverlay: {
         position: "absolute",
         top: SNAP_MAX_HEIGHT,

package/dist/ui/catalog.d.ts

@@ -10,7 +10,11 @@ export declare const snapJsonRenderCatalog: import("@json-render/core").Catalog<
         root: import("@json-render/core").SchemaType<"string", unknown>;
         elements: import("@json-render/core").SchemaType<"record", import("@json-render/core").SchemaType<"object", {
             type: import("@json-render/core").SchemaType<"ref", string>;
-            props: import("@json-render/core").SchemaType<"propsOf", string>;
+            props: {
+                optional: true;
+                kind: "propsOf";
+                inner?: string;
+            };
             children: {
                 optional: true;
                 kind: "array";

package/dist/ui/schema.d.ts

@@ -7,7 +7,11 @@ export declare const snapJsonRenderSchema: import("@json-render/core").Schema<{
         root: import("@json-render/core").SchemaType<"string", unknown>;
         elements: import("@json-render/core").SchemaType<"record", import("@json-render/core").SchemaType<"object", {
             type: import("@json-render/core").SchemaType<"ref", string>;
-            props: import("@json-render/core").SchemaType<"propsOf", string>;
+            props: {
+                optional: true;
+                kind: "propsOf";
+                inner?: string;
+            };
             children: {
                 optional: true;
                 kind: "array";

package/dist/ui/schema.js

@@ -8,7 +8,7 @@ export const snapJsonRenderSchema = defineSchema((s) => ({
         root: s.string(),
         elements: s.record(s.object({
             type: s.ref("catalog.components"),
-            props: s.propsOf("catalog.components"),
+            props: { ...s.propsOf("catalog.components"), optional: true },
             children: { ...s.array(s.string()), optional: true },
         })),
     }),

package/dist/validator.js

@@ -1,5 +1,6 @@
 import { snapResponseSchema } from "./schemas.js";
 import { MAX_CHILDREN, MAX_DEPTH, MAX_ELEMENTS, MAX_ROOT_CHILDREN, SPEC_VERSION_1 } from "./constants.js";
+import { snapJsonRenderCatalog } from "./ui/catalog.js";
 // ─── Helpers ──────────────────────────────────────────
 /** Actions whose `params.target` must be a valid URL. */
 const URL_TARGET_ACTIONS = new Set(["submit", "open_url", "open_mini_app"]);
@@ -202,6 +203,10 @@ export function validateSnapResponse(json) {
         if (urlIssues.length > 0) {
             return { valid: false, issues: urlIssues };
         }
+        const catalogResult = snapJsonRenderCatalog.validate(ui);
+        if (!catalogResult.success) {
+            return { valid: false, issues: catalogResult.error?.issues ?? [] };
+        }
     }
     return { valid: true, issues: [] };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farcaster/snap",
-  "version": "1.17.0",
+  "version": "1.17.2",
   "description": "Farcaster Snaps 🫰",
   "repository": {
     "type": "git",

package/src/react-native/index.tsx

@@ -29,6 +29,7 @@ export function SnapCard({
   showOverflowWarning = false,
   onValidationError,
   validationErrorFallback,
+  actionError,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -43,6 +44,8 @@ export function SnapCard({
   onValidationError?: (result: ValidationResult) => void;
   /** Custom fallback rendered when validation fails (v2 only). */
   validationErrorFallback?: ReactNode;
+  /** Server-side action error message to display inline. */
+  actionError?: string | null;
 }) {
   if (snap.version === SPEC_VERSION_2) {
     return (
@@ -56,6 +59,7 @@ export function SnapCard({
         showOverflowWarning={showOverflowWarning}
         onValidationError={onValidationError}
         validationErrorFallback={validationErrorFallback}
+        actionError={actionError}
       />
     );
   }
@@ -68,6 +72,7 @@ export function SnapCard({
       appearance={appearance}
       colors={colors}
       borderRadius={borderRadius}
+      actionError={actionError}
     />
   );
 }

package/src/react-native/v1/snap-view.tsx

@@ -1,4 +1,4 @@
-import { View, StyleSheet } from "react-native";
+import { View, Text, StyleSheet } from "react-native";
 import { SnapThemeProvider, useSnapTheme, type SnapNativeColors } from "../theme";
 import { SnapViewCoreInner } from "../snap-view-core";
 import type { SnapPage, SnapActionHandlers } from "../types";
@@ -46,31 +46,52 @@ function SnapCardV1Inner({
   handlers,
   loading = false,
   borderRadius,
+  actionError,
+  appearance,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
   loading?: boolean;
   borderRadius: number;
+  actionError?: string | null;
+  appearance: "light" | "dark";
 }) {
   const { colors } = useSnapTheme();
 
   return (
-    <View style={cardStyles.frameRing}>
-      <View
-        style={[
-          cardStyles.card,
-          {
-            borderRadius,
-            borderColor: colors.border,
-            backgroundColor: colors.surface,
-          },
-        ]}
-      >
-        <View style={cardStyles.body}>
-          <SnapViewV1Inner snap={snap} handlers={handlers} loading={loading} />
+    <>
+      <View style={cardStyles.frameRing}>
+        <View
+          style={[
+            cardStyles.card,
+            {
+              borderRadius,
+              borderColor: colors.border,
+              backgroundColor: colors.surface,
+            },
+          ]}
+        >
+          <View style={cardStyles.body}>
+            <SnapViewV1Inner snap={snap} handlers={handlers} loading={loading} />
+          </View>
         </View>
       </View>
-    </View>
+      {actionError && (
+        <Text
+          style={[
+            cardStyles.actionError,
+            {
+              color:
+                appearance === "dark"
+                  ? "rgba(255,100,100,0.9)"
+                  : "rgba(200,0,0,0.8)",
+            },
+          ]}
+        >
+          {actionError}
+        </Text>
+      )}
+    </>
   );
 }
 
@@ -81,6 +102,7 @@ export function SnapCardV1({
   appearance = "dark",
   colors,
   borderRadius = 16,
+  actionError,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -88,6 +110,7 @@ export function SnapCardV1({
   appearance?: "light" | "dark";
   colors?: Partial<SnapNativeColors>;
   borderRadius?: number;
+  actionError?: string | null;
 }) {
   return (
     <SnapThemeProvider appearance={appearance} colors={colors}>
@@ -96,6 +119,8 @@ export function SnapCardV1({
         handlers={handlers}
         loading={loading}
         borderRadius={borderRadius}
+        actionError={actionError}
+        appearance={appearance}
       />
     </SnapThemeProvider>
   );
@@ -105,4 +130,5 @@ const cardStyles = StyleSheet.create({
   frameRing: { alignSelf: "stretch" },
   card: { overflow: "hidden", borderWidth: 1, minHeight: 120 },
   body: { paddingHorizontal: 16, paddingVertical: 16 },
+  actionError: { paddingHorizontal: 12, paddingVertical: 8, fontSize: 13 },
 });

package/src/react-native/v2/snap-view.tsx

@@ -121,6 +121,8 @@ function SnapCardV2Inner({
   showOverflowWarning,
   onValidationError,
   validationErrorFallback,
+  actionError,
+  appearance,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -129,42 +131,61 @@ function SnapCardV2Inner({
   showOverflowWarning: boolean;
   onValidationError?: (result: ValidationResult) => void;
   validationErrorFallback?: ReactNode;
+  actionError?: string | null;
+  appearance: "light" | "dark";
 }) {
   const { colors } = useSnapTheme();
   const maxHeight = showOverflowWarning ? SNAP_WARNING_HEIGHT : SNAP_MAX_HEIGHT;
 
   return (
-    <View style={cardStyles.frameRing}>
-      <View
-        style={[
-          cardStyles.card,
-          {
-            borderRadius,
-            maxHeight,
-            borderColor: colors.border,
-            backgroundColor: colors.surface,
-          },
-        ]}
-      >
-        <View style={cardStyles.body}>
-          <SnapViewV2Inner
-            snap={snap}
-            handlers={handlers}
-            loading={loading}
-            onValidationError={onValidationError}
-            validationErrorFallback={validationErrorFallback}
-          />
-        </View>
-        {showOverflowWarning && (
-          <View style={cardStyles.warningOverlay}>
-            <View style={cardStyles.warningLine} />
-            <View style={cardStyles.warningLabel}>
-              <Text style={cardStyles.warningLabelText}>{SNAP_MAX_HEIGHT}px</Text>
-            </View>
+    <>
+      <View style={cardStyles.frameRing}>
+        <View
+          style={[
+            cardStyles.card,
+            {
+              borderRadius,
+              maxHeight,
+              borderColor: colors.border,
+              backgroundColor: colors.surface,
+            },
+          ]}
+        >
+          <View style={cardStyles.body}>
+            <SnapViewV2Inner
+              snap={snap}
+              handlers={handlers}
+              loading={loading}
+              onValidationError={onValidationError}
+              validationErrorFallback={validationErrorFallback}
+            />
           </View>
-        )}
+          {showOverflowWarning && (
+            <View style={cardStyles.warningOverlay}>
+              <View style={cardStyles.warningLine} />
+              <View style={cardStyles.warningLabel}>
+                <Text style={cardStyles.warningLabelText}>{SNAP_MAX_HEIGHT}px</Text>
+              </View>
+            </View>
+          )}
+        </View>
       </View>
-    </View>
+      {actionError && (
+        <Text
+          style={[
+            cardStyles.actionError,
+            {
+              color:
+                appearance === "dark"
+                  ? "rgba(255,100,100,0.9)"
+                  : "rgba(200,0,0,0.8)",
+            },
+          ]}
+        >
+          {actionError}
+        </Text>
+      )}
+    </>
   );
 }
 
@@ -178,6 +199,7 @@ export function SnapCardV2({
   showOverflowWarning = false,
   onValidationError,
   validationErrorFallback,
+  actionError,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -188,6 +210,7 @@ export function SnapCardV2({
   showOverflowWarning?: boolean;
   onValidationError?: (result: ValidationResult) => void;
   validationErrorFallback?: ReactNode;
+  actionError?: string | null;
 }) {
   return (
     <SnapThemeProvider appearance={appearance} colors={colors}>
@@ -199,6 +222,8 @@ export function SnapCardV2({
         showOverflowWarning={showOverflowWarning}
         onValidationError={onValidationError}
         validationErrorFallback={validationErrorFallback}
+        actionError={actionError}
+        appearance={appearance}
       />
     </SnapThemeProvider>
   );
@@ -208,6 +233,7 @@ const cardStyles = StyleSheet.create({
   frameRing: { alignSelf: "stretch" },
   card: { overflow: "hidden", borderWidth: 1, minHeight: 120 },
   body: { paddingHorizontal: 16, paddingVertical: 16 },
+  actionError: { paddingHorizontal: 12, paddingVertical: 8, fontSize: 13 },
   warningOverlay: {
     position: "absolute",
     top: SNAP_MAX_HEIGHT,

package/src/ui/schema.ts

@@ -11,7 +11,7 @@ export const snapJsonRenderSchema = defineSchema(
       elements: s.record(
         s.object({
           type: s.ref("catalog.components"),
-          props: s.propsOf("catalog.components"),
+          props: { ...s.propsOf("catalog.components"), optional: true },
           children: { ...s.array(s.string()), optional: true },
         }),
       ),

package/src/validator.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { snapResponseSchema } from "./schemas";
 import { MAX_CHILDREN, MAX_DEPTH, MAX_ELEMENTS, MAX_ROOT_CHILDREN, SPEC_VERSION_1 } from "./constants";
+import { snapJsonRenderCatalog } from "./ui/catalog.js";
 
 export type ValidationResult = {
   valid: boolean;
@@ -255,6 +256,11 @@ export function validateSnapResponse(json: unknown): ValidationResult {
     if (urlIssues.length > 0) {
       return { valid: false, issues: urlIssues };
     }
+
+    const catalogResult = snapJsonRenderCatalog.validate(ui);
+    if (!catalogResult.success) {
+      return { valid: false, issues: catalogResult.error?.issues ?? [] };
+    }
   }
 
   return { valid: true, issues: [] };