@farcaster/snap 2.0.1 → 2.0.3

package/dist/validator.js

@@ -3,7 +3,12 @@ import { MAX_CHILDREN, MAX_DEPTH, MAX_ELEMENTS, MAX_ROOT_CHILDREN, SPEC_VERSION_
 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"]);
+const URL_TARGET_ACTIONS = new Set([
+    "submit",
+    "open_url",
+    "open_snap",
+    "open_mini_app",
+]);
 /** Image file extensions allowed in image URLs. */
 const ALLOWED_IMAGE_EXTENSIONS = new Set(["jpg", "jpeg", "png", "gif", "webp"]);
 /**
@@ -129,7 +134,7 @@ function validateStructure(ui) {
 /**
  * Validate all URLs in the snap:
  * - image.url: must be HTTPS with allowed extension
- * - action target URLs (submit, open_url, open_mini_app): must be HTTPS
+ * - action target URLs (submit, open_url, open_snap, open_mini_app): must be HTTPS
  */
 function validateUrls(elements) {
     const issues = [];

package/llms.txt

@@ -68,7 +68,7 @@ Top-level fields: `version` (required, `"1.0"` or `"2.0"`), `theme` (optional, `
 - `title` (string, required, max 100)
 - `description` (string, optional, max 160)
 - `variant` (optional): `"default"`. Default: `"default"`
-- Children render in the actions slot (right side)
+- Children render in the actions slot (right side). Badges, buttons, and icons are all valid — but the item itself is not interactive, so avoid navigation-style icons (`chevron-right`, `arrow-right`, `external-link`) that imply the row navigates.
 
 **progress** — Horizontal progress bar.
 - `value` (number, required, 0 to max)
@@ -165,7 +165,7 @@ Bound to buttons via `on.press`:
 | `open_mini_app` | `target` (URL) | Open as Farcaster mini app |
 | `view_cast` | `hash` (string) | Navigate to a cast |
 | `view_profile` | `fid` (number) | Navigate to a profile |
-| `compose_cast` | `text?`, `channelKey?`, `embeds?` | Open cast composer |
+| `compose_cast` | `text?`, `channelKey?`, `embeds?` | Open cast composer. Put URLs in `embeds`, not `text` |
 | `view_token` | `token` (CAIP-19) | View token in wallet |
 | `send_token` | `token`, `amount?`, `recipientFid?`, `recipientAddress?` | Send token flow |
 | `swap_token` | `sellToken?`, `buyToken?` | Swap token flow |
@@ -174,6 +174,8 @@ Bound to buttons via `on.press`:
 
 `arrow-right`, `arrow-left`, `external-link`, `chevron-right`, `check`, `x`, `alert-triangle`, `info`, `clock`, `heart`, `message-circle`, `repeat`, `share`, `user`, `users`, `star`, `trophy`, `zap`, `flame`, `gift`, `image`, `play`, `pause`, `wallet`, `coins`, `plus`, `minus`, `refresh-cw`, `bookmark`, `thumbs-up`, `thumbs-down`, `trending-up`, `trending-down`
 
+`chevron-right`, `arrow-right`, and `external-link` are navigation/disclosure affordances — only use them when the surrounding element actually navigates (e.g. a button bound to `open_url` or `open_snap`). Never place them inside an `item`'s actions slot; `item` is not interactive.
+
 ## Color Palette
 
 `gray`, `blue`, `red`, `amber`, `green`, `teal`, `purple`, `pink`

package/package.json

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

package/src/react/components/action-button.tsx

@@ -39,19 +39,22 @@ export function SnapActionButton({
   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" as const,
+    ...(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 (
     <div className="w-full min-w-0 flex-1">

package/src/react/index.tsx

@@ -59,6 +59,7 @@ export function SnapCard({
   validationErrorFallback,
   actionError,
   plain = false,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -73,6 +74,8 @@ export function SnapCard({
   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;
 }) {
   if (snap.version === SPEC_VERSION_2) {
     return (
@@ -87,6 +90,7 @@ export function SnapCard({
         validationErrorFallback={validationErrorFallback}
         actionError={actionError}
         plain={plain}
+        loadingOverlay={loadingOverlay}
       />
     );
   }
@@ -100,6 +104,7 @@ export function SnapCard({
       maxWidth={maxWidth}
       actionError={actionError}
       plain={plain}
+      loadingOverlay={loadingOverlay}
     />
   );
 }

package/src/react/snap-view-core.tsx

@@ -8,6 +8,7 @@ import { resolveSnapPaletteHex } from "./lib/resolve-palette-hex";
 import { snapPreviewPrimaryCssProperties } from "./lib/preview-primary-css";
 import {
   type CSSProperties,
+  type ReactNode,
   useCallback,
   useEffect,
   useMemo,
@@ -111,7 +112,7 @@ function ConfettiOverlay() {
   );
 }
 
-function SnapLoadingOverlay({
+export function SnapLoadingOverlay({
   appearance,
   accentHex,
   active,
@@ -197,11 +198,17 @@ export function SnapViewCore({
   handlers,
   loading = false,
   appearance = "dark",
+  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;
 }) {
   const spec = snap.ui;
   const initialState = useMemo(() => spec.state ?? { inputs: {} }, [spec]);
@@ -265,6 +272,9 @@ export function SnapViewCore({
         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;
@@ -312,11 +322,15 @@ export function SnapViewCore({
   return (
     <div style={{ position: "relative", width: "100%" }}>
       {showConfetti && <ConfettiOverlay />}
-      <SnapLoadingOverlay
-        appearance={appearance}
-        accentHex={accentHex}
-        active={loading}
-      />
+      {loadingOverlay === undefined ? (
+        <SnapLoadingOverlay
+          appearance={appearance}
+          accentHex={accentHex}
+          active={loading}
+        />
+      ) : loading ? (
+        <>{loadingOverlay}</>
+      ) : null}
 
       <div style={previewSurfaceStyle}>
         <SnapPreviewAccentProvider

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

@@ -1,7 +1,8 @@
 "use client";
 
-import { useEffect, useRef, useState } from "react";
-import { SnapViewCore } from "../snap-view-core";
+import { type ReactNode, useEffect, useMemo, useRef, useState } from "react";
+import { SnapViewCore, SnapLoadingOverlay } from "../snap-view-core";
+import { resolveSnapPaletteHex } from "../lib/resolve-palette-hex";
 import type { SnapPage, SnapActionHandlers } from "../index";
 
 const SNAP_MAX_HEIGHT = 500;
@@ -11,11 +12,14 @@ export function SnapViewV1({
   handlers,
   loading = false,
   appearance = "dark",
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
   loading?: boolean;
   appearance?: "light" | "dark";
+  /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+  loadingOverlay?: ReactNode;
 }) {
   return (
     <SnapViewCore
@@ -23,6 +27,7 @@ export function SnapViewV1({
       handlers={handlers}
       loading={loading}
       appearance={appearance}
+      loadingOverlay={loadingOverlay}
     />
   );
 }
@@ -35,6 +40,7 @@ export function SnapCardV1({
   maxWidth = 480,
   actionError,
   plain = false,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -43,6 +49,8 @@ export function SnapCardV1({
   maxWidth?: number;
   actionError?: string | null;
   plain?: boolean;
+  /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+  loadingOverlay?: ReactNode;
 }) {
   const isDark = appearance === "dark";
   const borderColor = isDark ? "rgba(255,255,255,0.1)" : "rgba(0,0,0,0.1)";
@@ -86,6 +94,11 @@ export function SnapCardV1({
 
   const isClipped = isExpandable && !isExpanded;
 
+  const accentHex = useMemo(
+    () => resolveSnapPaletteHex(snap.theme?.accent ?? "purple", appearance),
+    [snap.theme?.accent, appearance],
+  );
+
   return (
     <div
       style={{
@@ -116,9 +129,19 @@ export function SnapCardV1({
             handlers={handlers}
             loading={loading}
             appearance={appearance}
+            loadingOverlay={null}
           />
         </div>
       </div>
+      {loadingOverlay === undefined ? (
+        <SnapLoadingOverlay
+          appearance={appearance}
+          accentHex={accentHex}
+          active={loading}
+        />
+      ) : loading ? (
+        <>{loadingOverlay}</>
+      ) : null}
       {isExpandable ? (
         <div
           style={{

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

@@ -3,7 +3,8 @@
 import { type ReactNode, useEffect, useMemo } from "react";
 import { validateSnapResponse } from "../../validator.js";
 import type { ValidationResult } from "../../validator.js";
-import { SnapViewCore } from "../snap-view-core";
+import { SnapViewCore, SnapLoadingOverlay } from "../snap-view-core";
+import { resolveSnapPaletteHex } from "../lib/resolve-palette-hex";
 import type { SnapPage, SnapActionHandlers } from "../index";
 
 const SNAP_MAX_HEIGHT = 500;
@@ -45,6 +46,7 @@ export function SnapViewV2({
   appearance = "dark",
   onValidationError,
   validationErrorFallback,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -52,6 +54,8 @@ export function SnapViewV2({
   appearance?: "light" | "dark";
   onValidationError?: (result: ValidationResult) => void;
   validationErrorFallback?: ReactNode;
+  /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+  loadingOverlay?: ReactNode;
 }) {
   const validation = useMemo(() => validateSnapResponse(snap), [snap]);
   const valid = validation.valid;
@@ -79,6 +83,7 @@ export function SnapViewV2({
       handlers={handlers}
       loading={loading}
       appearance={appearance}
+      loadingOverlay={loadingOverlay}
     />
   );
 }
@@ -96,6 +101,7 @@ export function SnapCardV2({
   validationErrorFallback,
   actionError,
   plain = false,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -107,12 +113,18 @@ export function SnapCardV2({
   validationErrorFallback?: ReactNode;
   actionError?: string | null;
   plain?: boolean;
+  /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+  loadingOverlay?: ReactNode;
 }) {
   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 (
     <>
@@ -138,8 +150,18 @@ export function SnapCardV2({
         appearance={appearance}
         onValidationError={onValidationError}
         validationErrorFallback={validationErrorFallback}
+        loadingOverlay={null}
       />
       </div>
+      {loadingOverlay === undefined ? (
+        <SnapLoadingOverlay
+          appearance={appearance}
+          accentHex={accentHex}
+          active={loading}
+        />
+      ) : loading ? (
+        <>{loadingOverlay}</>
+      ) : null}
       {showOverflowWarning && (
         <div
           style={{

package/src/react-native/index.tsx

@@ -31,6 +31,7 @@ export function SnapCard({
   validationErrorFallback,
   actionError,
   plain = false,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -49,6 +50,8 @@ export function SnapCard({
   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;
 }) {
   if (snap.version === SPEC_VERSION_2) {
     return (
@@ -64,6 +67,7 @@ export function SnapCard({
         validationErrorFallback={validationErrorFallback}
         actionError={actionError}
         plain={plain}
+        loadingOverlay={loadingOverlay}
       />
     );
   }
@@ -78,6 +82,7 @@ export function SnapCard({
       borderRadius={borderRadius}
       actionError={actionError}
       plain={plain}
+      loadingOverlay={loadingOverlay}
     />
   );
 }

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

@@ -2,7 +2,14 @@ import type { Spec } from "@json-render/core";
 import { snapJsonRenderCatalog } from "@farcaster/snap/ui";
 import { SnapCatalogView } from "./catalog-renderer";
 import { useSnapTheme } from "./theme";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
 import { ActivityIndicator, StyleSheet, View } from "react-native";
 import {
   DEFAULT_THEME_ACCENT,
@@ -66,10 +73,16 @@ export function SnapViewCoreInner({
   snap,
   handlers,
   loading = false,
+  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;
 }) {
   const { mode } = useSnapTheme();
   const spec = snap.ui;
@@ -127,6 +140,9 @@ export function SnapViewCoreInner({
       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;
@@ -169,19 +185,16 @@ export function SnapViewCoreInner({
 
   return (
     <View style={styles.container}>
-      {loading ? (
-        <View
-          style={[
-            styles.overlay,
-            {
-              backgroundColor:
-                mode === "dark" ? "rgba(0,0,0,0.1)" : "rgba(255,255,255,0.2)",
-            },
-          ]}
-        >
-          <ActivityIndicator size="large" color={accentHex} />
-        </View>
-      ) : null}
+      {loading
+        ? loadingOverlay === undefined
+          ? (
+            <SnapLoadingOverlay
+              appearance={mode}
+              accentHex={accentHex}
+            />
+          )
+          : loadingOverlay
+        : null}
       <SnapCatalogView
         key={pageKey}
         spec={spec}
@@ -196,6 +209,30 @@ export function SnapViewCoreInner({
   );
 }
 
+export function SnapLoadingOverlay({
+  appearance,
+  accentHex,
+}: {
+  appearance: "light" | "dark";
+  accentHex: string;
+}) {
+  return (
+    <View
+      style={[
+        styles.overlay,
+        {
+          backgroundColor:
+            appearance === "dark"
+              ? "rgba(0,0,0,0.1)"
+              : "rgba(255,255,255,0.2)",
+        },
+      ]}
+    >
+      <ActivityIndicator size="large" color={accentHex} />
+    </View>
+  );
+}
+
 const styles = StyleSheet.create({
   container: {
     width: "100%",

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

@@ -1,7 +1,11 @@
-import { useEffect, useState } from "react";
+import { type ReactNode, useEffect, useState } from "react";
 import { View, Text, StyleSheet, Pressable } from "react-native";
 import { SnapThemeProvider, useSnapTheme, type SnapNativeColors } from "../theme";
-import { SnapViewCoreInner } from "../snap-view-core";
+import {
+  SnapLoadingOverlay,
+  SnapViewCoreInner,
+  resolveAccentHex,
+} from "../snap-view-core";
 import type { SnapPage, SnapActionHandlers } from "../types";
 
 const SNAP_MAX_HEIGHT = 500;
@@ -12,13 +16,20 @@ export function SnapViewV1Inner({
   snap,
   handlers,
   loading = false,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
   loading?: boolean;
+  loadingOverlay?: ReactNode;
 }) {
   return (
-    <SnapViewCoreInner snap={snap} handlers={handlers} loading={loading} />
+    <SnapViewCoreInner
+      snap={snap}
+      handlers={handlers}
+      loading={loading}
+      loadingOverlay={loadingOverlay}
+    />
   );
 }
 
@@ -28,16 +39,24 @@ export function SnapViewV1({
   loading = false,
   appearance = "dark",
   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;
 }) {
   return (
     <SnapThemeProvider appearance={appearance} colors={colors}>
-      <SnapViewV1Inner snap={snap} handlers={handlers} loading={loading} />
+      <SnapViewV1Inner
+        snap={snap}
+        handlers={handlers}
+        loading={loading}
+        loadingOverlay={loadingOverlay}
+      />
     </SnapThemeProvider>
   );
 }
@@ -52,6 +71,7 @@ function SnapCardV1Inner({
   actionError,
   appearance,
   plain,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -60,8 +80,10 @@ function SnapCardV1Inner({
   actionError?: string | null;
   appearance: "light" | "dark";
   plain: boolean;
+  loadingOverlay?: ReactNode;
 }) {
-  const { colors } = useSnapTheme();
+  const { colors, mode } = useSnapTheme();
+  const accentHex = resolveAccentHex(snap.theme?.accent, mode);
   const [contentHeight, setContentHeight] = useState(0);
   const [isExpanded, setIsExpanded] = useState(false);
 
@@ -107,9 +129,15 @@ function SnapCardV1Inner({
                 snap={snap}
                 handlers={handlers}
                 loading={loading}
+                loadingOverlay={null}
               />
             </View>
           </View>
+          {loading
+            ? loadingOverlay === undefined
+              ? <SnapLoadingOverlay appearance={mode} accentHex={accentHex} />
+              : loadingOverlay
+            : null}
           {isExpandable ? (
             <View
               style={[
@@ -170,6 +198,7 @@ export function SnapCardV1({
   borderRadius = 16,
   actionError,
   plain = false,
+  loadingOverlay,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -179,6 +208,8 @@ export function SnapCardV1({
   borderRadius?: number;
   actionError?: string | null;
   plain?: boolean;
+  /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
+  loadingOverlay?: ReactNode;
 }) {
   return (
     <SnapThemeProvider appearance={appearance} colors={colors}>
@@ -190,6 +221,7 @@ export function SnapCardV1({
         actionError={actionError}
         appearance={appearance}
         plain={plain}
+        loadingOverlay={loadingOverlay}
       />
     </SnapThemeProvider>
   );