@farcaster/snap 2.0.2 → 2.1.0

package/dist/validator.js

@@ -1,5 +1,5 @@
 import { snapResponseSchema } from "./schemas.js";
-import { MAX_CHILDREN, MAX_DEPTH, MAX_ELEMENTS, MAX_ROOT_CHILDREN, SPEC_VERSION_1 } from "./constants.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. */
@@ -9,8 +9,6 @@ const URL_TARGET_ACTIONS = new Set([
     "open_snap",
     "open_mini_app",
 ]);
-/** Image file extensions allowed in image URLs. */
-const ALLOWED_IMAGE_EXTENSIONS = new Set(["jpg", "jpeg", "png", "gif", "webp"]);
 /**
  * Returns true if the URL is a loopback address (localhost dev exception).
  */
@@ -38,31 +36,6 @@ function validateUrl(raw) {
         return `javascript: URIs are not allowed`;
     return `URL must use HTTPS (got ${url.protocol.replace(":", "")}): "${raw}"`;
 }
-/**
- * Validate an image URL: must pass URL validation + have an allowed extension.
- */
-function validateImageUrl(raw) {
-    const urlError = validateUrl(raw);
-    if (urlError)
-        return urlError;
-    let url;
-    try {
-        url = new URL(raw);
-    }
-    catch {
-        return null; // already caught above
-    }
-    const pathname = url.pathname;
-    const lastDot = pathname.lastIndexOf(".");
-    if (lastDot === -1) {
-        return `Image URL must end with a supported extension (${[...ALLOWED_IMAGE_EXTENSIONS].join(", ")}): "${raw}"`;
-    }
-    const ext = pathname.slice(lastDot + 1).toLowerCase();
-    if (!ALLOWED_IMAGE_EXTENSIONS.has(ext)) {
-        return `Image URL has unsupported extension ".${ext}" (allowed: ${[...ALLOWED_IMAGE_EXTENSIONS].join(", ")}): "${raw}"`;
-    }
-    return null;
-}
 // ─── Depth measurement ────────────────────────────────
 /**
  * Walk the element tree from `root` and return the max depth reached.
@@ -133,8 +106,8 @@ function validateStructure(ui) {
 // ─── URL validation ───────────────────────────────────
 /**
  * Validate all URLs in the snap:
- * - image.url: must be HTTPS with allowed extension
- * - action target URLs (submit, open_url, open_snap, open_mini_app): must be HTTPS
+ * - image.url: must use HTTPS (or HTTP on loopback for dev)
+ * - action target URLs (submit, open_url, open_snap, open_mini_app): must use HTTPS (or HTTP on loopback for dev)
  */
 function validateUrls(elements) {
     const issues = [];
@@ -142,7 +115,7 @@ function validateUrls(elements) {
     for (const [id, el] of Object.entries(els)) {
         // Validate image URLs
         if (el.type === "image" && typeof el.props?.url === "string") {
-            const error = validateImageUrl(el.props.url);
+            const error = validateUrl(el.props.url);
             if (error) {
                 issues.push({
                     code: "custom",
@@ -191,11 +164,13 @@ export function validateSnapResponse(json) {
     if (!(ui.root in ui.elements)) {
         return {
             valid: false,
-            issues: [{
+            issues: [
+                {
                     code: "custom",
                     message: `ui.root "${ui.root}" does not exist in ui.elements`,
                     path: ["ui", "root"],
-                }],
+                },
+            ],
         };
     }
     // Structural limits and URL validation only apply to v2+ snaps

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)
@@ -98,7 +98,8 @@ Top-level fields: `version` (required, `"1.0"` or `"2.0"`), `theme` (optional, `
 - `cells` (array, required): sparse list of `{ row, col, color?: PaletteColor, content?: string }`
 - `gap` (optional): `"none"` (0px) | `"sm"` (1px) | `"md"` (2px) | `"lg"` (4px). Default: `"sm"`
 - `rowHeight` (number, optional, 8–64): pixel height per row. Default: 28. Grid height = rows × rowHeight
-- `select` (optional): `"off"` | `"single"` | `"multiple"`. Default: `"off"`. Taps write to `inputs[name]`
+- `select` (optional): `"off"` | `"single"` | `"multiple"`. Default: `"off"`. With `select: "off"`, bind `on.press` for press-to-act (each press writes `"row,col"` to `inputs[name]` and fires the action). With `"single"` / `"multiple"`, presses accumulate selection state and pair with a separate submit `button`; `on.press` is ignored.
+- Events: `press` — fires on cell press, only when `select: "off"`; `inputs[name]` is set to `"row,col"` before the bound action runs
 
 ### Container Components
 
@@ -165,7 +166,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 +175,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`
@@ -194,6 +197,26 @@ import { withTursoServerless, createInMemoryDataStore } from "@farcaster/snap-tu
 - `@farcaster/snap-hono` — Hono adapter (`registerSnapHandler`)
 - `@farcaster/snap-turso` — `withTursoServerless`, `DataStore` / `DataStoreValue`, in-memory and Turso helpers
 
+## Template Project Setup
+
+The `template/` directory is the starting point for a snap. It's an ESM project
+(`"type": "module"`) with `moduleResolution: "NodeNext"`.
+
+**ESM import rule (CRITICAL)**: all local relative imports must include the `.js`
+extension, even though the source files are `.ts`:
+
+```ts
+// ✅ correct
+import { foo } from "./foo.js";
+
+// ❌ wrong — fails `pnpm build`; on deploy every route returns 500 FUNCTION_INVOCATION_FAILED
+import { foo } from "./foo";
+```
+
+`tsx` dev accepts bare imports, so the bug only surfaces on deploy. Always run
+`pnpm build` (`tsc --noEmit`) before deploying — NodeNext makes this a build-time error.
+Bare package imports (`hono`, `@farcaster/snap`, etc.) do not need an extension.
+
 ## Full Documentation
 
 https://docs.farcaster.xyz/snap

package/package.json

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

package/src/react/components/cell-grid.tsx

@@ -7,17 +7,21 @@ import { POST_GRID_TAP_KEY } from "@farcaster/snap";
 import { useSnapColors } from "../hooks/use-snap-colors";
 
 export function SnapCellGrid({
-  element: { props },
+  element: { props, on },
+  emit,
 }: {
-  element: { props: Record<string, unknown> };
+  element: { props: Record<string, unknown>; on?: Record<string, unknown> };
+  emit: (name: string) => void;
 }) {
   const { get, set } = useStateStore();
   const colors = useSnapColors();
   const cols = Number(props.cols ?? 2);
   const rows = Number(props.rows ?? 2);
   const select = String(props.select ?? "off");
-  const interactive = select !== "off";
   const isMultiple = select === "multiple";
+  const isSelectable = select !== "off";
+  const hasPressAction = Boolean(on?.press);
+  const interactive = isSelectable || hasPressAction;
   const cells = Array.isArray(props.cells) ? props.cells : [];
   const gap = String(props.gap ?? "sm");
   const gapMap: Record<string, number> = { none: 0, sm: 1, md: 2, lg: 4 };
@@ -36,7 +40,8 @@ export function SnapCellGrid({
     }
   }
 
-  const isSelected = (r: number, c: number) => selectedSet.has(`${r},${c}`);
+  const isSelected = (r: number, c: number) =>
+    isSelectable && selectedSet.has(`${r},${c}`);
 
   const handleTap = (r: number, c: number) => {
     const key = `${r},${c}`;
@@ -48,6 +53,7 @@ export function SnapCellGrid({
     } else {
       set(tapPath, key);
     }
+    if (hasPressAction) emit("press");
   };
 
   const cellMap = new Map<string, { color?: string; content?: string }>();
@@ -99,7 +105,7 @@ export function SnapCellGrid({
     }
   }
 
-  const selectionLabel = interactive && selectedSet.size > 0
+  const selectionLabel = isSelectable && selectedSet.size > 0
     ? `inputs.${name}: ${[...selectedSet].join(isMultiple ? " | " : "")}`
     : null;
 

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]);
@@ -232,7 +239,11 @@ export function SnapViewCore({
     setPageKey((k) => k + 1);
   }, [spec]);
 
-  const showConfetti = snap.effects?.includes("confetti");
+  const showConfetti = snap.effects?.includes("confetti") ?? false;
+  const [confettiKey, setConfettiKey] = useState(0);
+  useEffect(() => {
+    if (showConfetti) setConfettiKey((k) => k + 1);
+  }, [showConfetti, snap]);
 
   const accentName = snap.theme?.accent ?? "purple";
 
@@ -314,12 +325,16 @@ export function SnapViewCore({
 
   return (
     <div style={{ position: "relative", width: "100%" }}>
-      {showConfetti && <ConfettiOverlay />}
-      <SnapLoadingOverlay
-        appearance={appearance}
-        accentHex={accentHex}
-        active={loading}
-      />
+      {showConfetti && <ConfettiOverlay key={confettiKey} />}
+      {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,76 +94,97 @@ export function SnapCardV1({
 
   const isClipped = isExpandable && !isExpanded;
 
+  const accentHex = useMemo(
+    () => resolveSnapPaletteHex(snap.theme?.accent ?? "purple", appearance),
+    [snap.theme?.accent, appearance],
+  );
+
   return (
     <div
       style={{
         position: "relative",
         width: "100%",
         maxWidth,
-        overflow: "hidden",
-        ...(plain ? {} : {
-          borderRadius: 16,
-          border: `1px solid ${borderColor}`,
-          backgroundColor: surfaceBg,
-        }),
       }}
     >
       <div
-        style={
-          isClipped
-            ? {
-                maxHeight: SNAP_MAX_HEIGHT,
-                overflow: "hidden",
-              }
-            : undefined
-        }
+        style={{
+          position: "relative",
+          overflow: "hidden",
+          ...(plain ? {} : {
+            borderRadius: 16,
+            border: `1px solid ${borderColor}`,
+            backgroundColor: surfaceBg,
+          }),
+        }}
       >
-        <div ref={contentRef} style={plain ? undefined : { padding: 16 }}>
-          <SnapViewV1
-            snap={snap}
-            handlers={handlers}
-            loading={loading}
+        <div
+          style={
+            isClipped
+              ? {
+                  maxHeight: SNAP_MAX_HEIGHT,
+                  overflow: "hidden",
+                }
+              : undefined
+          }
+        >
+          <div ref={contentRef} style={plain ? undefined : { padding: 16 }}>
+            <SnapViewV1
+              snap={snap}
+              handlers={handlers}
+              loading={loading}
+              appearance={appearance}
+              loadingOverlay={null}
+            />
+          </div>
+        </div>
+        {loadingOverlay === undefined ? (
+          <SnapLoadingOverlay
             appearance={appearance}
+            accentHex={accentHex}
+            active={loading}
           />
-        </div>
+        ) : loading ? (
+          <>{loadingOverlay}</>
+        ) : null}
       </div>
       {isExpandable ? (
-        <div
+        <button
+          type="button"
+          aria-expanded={isExpanded}
+          onClick={() => setIsExpanded((value) => !value)}
           style={{
-            display: "flex",
-            justifyContent: "center",
-            padding: plain ? "8px 0 0" : "10px 16px 12px",
-            ...(plain
-              ? {}
-              : { borderTop: `1px solid ${borderColor}` }),
+            position: "absolute",
+            bottom: 0,
+            left: "50%",
+            transform: "translate(-50%, 50%)",
+            appearance: "none",
+            border: `1px solid ${borderColor}`,
+            borderRadius: 9999,
+            backgroundColor: isDark ? "rgba(30,30,30,0.6)" : "rgba(255,255,255,0.6)",
+            backdropFilter: "blur(12px) saturate(180%)",
+            WebkitBackdropFilter: "blur(12px) saturate(180%)",
+            color: toggleText,
+            padding: "2px 10px",
+            fontSize: 12,
+            lineHeight: "16px",
+            fontWeight: 600,
+            cursor: "pointer",
+            zIndex: 11,
+          }}
+          onMouseEnter={(event) => {
+            event.currentTarget.style.backgroundColor = isDark
+              ? "rgba(50,50,50,0.7)"
+              : "rgba(245,245,245,0.75)";
+          }}
+          onMouseLeave={(event) => {
+            event.currentTarget.style.backgroundColor = isDark
+              ? "rgba(30,30,30,0.6)"
+              : "rgba(255,255,255,0.6)";
           }}
         >
-          <button
-            type="button"
-            aria-expanded={isExpanded}
-            onClick={() => setIsExpanded((value) => !value)}
-            style={{
-              appearance: "none",
-              border: "none",
-              borderRadius: 9999,
-              backgroundColor: toggleBg,
-              color: toggleText,
-              padding: "6px 10px",
-              fontSize: 13,
-              lineHeight: "18px",
-              fontWeight: 600,
-              cursor: "pointer",
-            }}
-            onMouseEnter={(event) => {
-              event.currentTarget.style.backgroundColor = toggleBgHover;
-            }}
-            onMouseLeave={(event) => {
-              event.currentTarget.style.backgroundColor = toggleBg;
-            }}
-          >
-            {isExpanded ? "Show less" : "Show more"}
-          </button>
-        </div>
+          {isExpanded ? "Show less" : "Show more"}
+        </button>
       ) : null}
       {actionError && (
         <div