@farcaster/snap 2.0.3 → 2.1.0

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

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

package/dist/ui/catalog.js

@@ -90,7 +90,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
         },
         cell_grid: {
             props: cellGridProps,
-            description: "Cell grid — sparse colored cells on a rows×cols grid. Optional gap and selection mode (taps write to inputs[name]).",
+            description: "Cell grid — sparse colored cells on a rows×cols grid. Two interaction modes: leave select 'off' and bind on.press to fire an action per cell press (inputs[name] is the pressed 'row,col' before the action runs); or set select 'single'/'multiple' for press-to-select with a visual ring (no auto-fire — pair with a separate submit button). on.press is ignored when select is on.",
         },
     },
     actions: {

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

@@ -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
 
@@ -196,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.3",
+  "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/snap-view-core.tsx

@@ -239,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";
 
@@ -321,7 +325,7 @@ export function SnapViewCore({
 
   return (
     <div style={{ position: "relative", width: "100%" }}>
-      {showConfetti && <ConfettiOverlay />}
+      {showConfetti && <ConfettiOverlay key={confettiKey} />}
       {loadingOverlay === undefined ? (
         <SnapLoadingOverlay
           appearance={appearance}

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

@@ -105,80 +105,86 @@ export function SnapCardV1({
         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}
-            loadingOverlay={null}
+            accentHex={accentHex}
+            active={loading}
           />
-        </div>
+        ) : loading ? (
+          <>{loadingOverlay}</>
+        ) : null}
       </div>
-      {loadingOverlay === undefined ? (
-        <SnapLoadingOverlay
-          appearance={appearance}
-          accentHex={accentHex}
-          active={loading}
-        />
-      ) : loading ? (
-        <>{loadingOverlay}</>
-      ) : null}
       {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