@farcaster/snap 1.15.3 → 1.16.0

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

@@ -0,0 +1,340 @@
+"use client";
+
+import type { Spec } from "@json-render/core";
+import { snapJsonRenderCatalog } from "../ui/index.js";
+import { SnapCatalogView } from "./catalog-renderer";
+import { SnapPreviewAccentProvider } from "./accent-context";
+import { resolveSnapPaletteHex } from "./lib/resolve-palette-hex";
+import { snapPreviewPrimaryCssProperties } from "./lib/preview-primary-css";
+import {
+  type CSSProperties,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import type { JsonValue, SnapActionHandlers, SnapPage } from "./index";
+
+// ─── Internal helpers ──────────────────────────────────
+
+export function applyStatePaths(
+  model: Record<string, unknown>,
+  changes: { path: string; value: unknown }[] | Record<string, unknown>,
+): void {
+  const entries = Array.isArray(changes)
+    ? changes.map((c) => [c.path, c.value] as const)
+    : Object.entries(changes);
+  for (const [path, value] of entries) {
+    const trimmed = path.startsWith("/") ? path : `/${path}`;
+    const parts = trimmed.split("/").filter(Boolean);
+    if (parts.length < 2) continue;
+    const [top, ...rest] = parts;
+    if (top === "inputs") {
+      if (typeof model.inputs !== "object" || model.inputs === null) {
+        model.inputs = {};
+      }
+      const inputs = model.inputs as Record<string, unknown>;
+      if (rest.length === 1) {
+        inputs[rest[0]!] = value;
+      }
+      continue;
+    }
+    if (top === "theme") {
+      if (typeof model.theme !== "object" || model.theme === null) {
+        model.theme = {};
+      }
+      const theme = model.theme as Record<string, unknown>;
+      if (rest.length === 1) {
+        theme[rest[0]!] = value;
+      }
+    }
+  }
+}
+
+const CONFETTI_COLORS = [
+  "#8B5CF6",
+  "#EC4899",
+  "#3B82F6",
+  "#10B981",
+  "#F59E0B",
+  "#EF4444",
+  "#06B6D4",
+];
+
+function ConfettiOverlay() {
+  const pieces = useMemo(
+    () =>
+      Array.from({ length: 80 }, (_, i) => ({
+        id: i,
+        left: Math.random() * 100,
+        delay: Math.random() * 1.2,
+        duration: 2.5 + Math.random() * 2,
+        color:
+          CONFETTI_COLORS[Math.floor(Math.random() * CONFETTI_COLORS.length)],
+        size: 6 + Math.random() * 8,
+        rotation: Math.random() * 360,
+      })),
+    [],
+  );
+
+  return (
+    <div
+      style={{
+        position: "absolute",
+        inset: 0,
+        overflow: "hidden",
+        pointerEvents: "none",
+        zIndex: 20,
+      }}
+    >
+      {pieces.map(({ id, left, delay, duration, color, size, rotation }) => (
+        <div
+          key={id}
+          style={{
+            position: "absolute",
+            left: `${left}%`,
+            top: -20,
+            width: size,
+            height: size * 0.6,
+            backgroundColor: color,
+            borderRadius: 2,
+            transform: `rotate(${rotation}deg)`,
+            animation: `confettiFall ${duration}s ease-in ${delay}s forwards`,
+          }}
+        />
+      ))}
+      <style>{`@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)}}`}</style>
+    </div>
+  );
+}
+
+function SnapLoadingOverlay({
+  appearance,
+  accentHex,
+  active,
+}: {
+  appearance: "light" | "dark";
+  accentHex: string;
+  active: boolean;
+}) {
+  const isDark = appearance === "dark";
+  const tint = isDark ? "rgba(0, 0, 0, 0.1)" : "rgba(255, 255, 255, 0.2)";
+  const trackColor = isDark
+    ? "rgba(255, 255, 255, 0.12)"
+    : "rgba(15, 23, 42, 0.1)";
+
+  return (
+    <div
+      style={{
+        position: "absolute",
+        inset: 0,
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        zIndex: 10,
+        background: tint,
+        backdropFilter: active ? "blur(10px) saturate(1.05)" : "none",
+        WebkitBackdropFilter: active
+          ? "blur(10px) saturate(1.05)"
+          : "none",
+        opacity: active ? 1 : 0,
+        pointerEvents: active ? "auto" : "none",
+        transition: "opacity 0.28s ease, backdrop-filter 0.28s ease",
+      }}
+      aria-hidden={!active}
+      aria-busy={active ? true : undefined}
+      aria-live={active ? "polite" : undefined}
+      aria-label={active ? "Loading" : undefined}
+    >
+      <div
+        data-snap-loading-spinner
+        style={{
+          width: 30,
+          height: 30,
+          borderRadius: "50%",
+          border: `2.5px solid ${trackColor}`,
+          borderTopColor: accentHex,
+          opacity: 0.88,
+          animation: "snapViewSpin 0.75s linear infinite",
+          flexShrink: 0,
+        }}
+      />
+      <style>{`
+        @keyframes snapViewSpin {
+          to { transform: rotate(360deg); }
+        }
+        @media (prefers-reduced-motion: reduce) {
+          [data-snap-loading-spinner] {
+            animation: none;
+            border-top-color: ${accentHex};
+            opacity: 0.75;
+          }
+        }
+      `}</style>
+    </div>
+  );
+}
+
+const PALETTE = [
+  "gray",
+  "blue",
+  "red",
+  "amber",
+  "green",
+  "teal",
+  "purple",
+  "pink",
+] as const;
+
+// ─── SnapViewCore ────────────────────────────────────
+// Shared rendering logic used by both v1 and v2.
+
+export function SnapViewCore({
+  snap,
+  handlers,
+  loading = false,
+  appearance = "dark",
+}: {
+  snap: SnapPage;
+  handlers: SnapActionHandlers;
+  loading?: boolean;
+  appearance?: "light" | "dark";
+}) {
+  const spec = snap.ui;
+  const initialState = useMemo(() => spec.state ?? { inputs: {} }, [spec]);
+
+  const stateRef = useRef<Record<string, unknown>>(initialState);
+
+  useEffect(() => {
+    stateRef.current = {
+      inputs: {
+        ...((initialState.inputs ?? {}) as Record<string, unknown>),
+      },
+      theme: {
+        ...((initialState.theme ?? {}) as Record<string, unknown>),
+      },
+    };
+  }, [initialState]);
+
+  useEffect(() => {
+    const catalogResult = snapJsonRenderCatalog.validate(spec);
+    if (!catalogResult.success) {
+      // eslint-disable-next-line no-console
+      console.warn("[Snap] catalog validation issues:", catalogResult.error);
+    }
+  }, [spec]);
+
+  const [pageKey, setPageKey] = useState(0);
+  useEffect(() => {
+    setPageKey((k) => k + 1);
+  }, [spec]);
+
+  const showConfetti = snap.effects?.includes("confetti");
+
+  const accentName = snap.theme?.accent ?? "purple";
+
+  const accentHex = useMemo(
+    () => resolveSnapPaletteHex(accentName, appearance),
+    [accentName, appearance],
+  );
+
+  const previewSurfaceStyle = useMemo(() => {
+    const vars: Record<string, string> = {};
+    for (const c of PALETTE)
+      vars[`--snap-color-${c}`] = resolveSnapPaletteHex(c, appearance);
+    return {
+      ...snapPreviewPrimaryCssProperties(accentName, appearance),
+      ...vars,
+    } as CSSProperties;
+  }, [accentName, appearance]);
+
+  const handleAction = useCallback(
+    (name: unknown, params: unknown) => {
+      const inputs = (stateRef.current.inputs ?? {}) as Record<
+        string,
+        JsonValue
+      >;
+      const p = (params ?? {}) as Record<string, unknown>;
+      switch (name) {
+        case "submit":
+          handlers.submit(String(p.target ?? ""), inputs);
+          break;
+        case "open_url":
+          handlers.open_url(String(p.target ?? ""));
+          break;
+        case "open_mini_app":
+          handlers.open_mini_app(String(p.target ?? ""));
+          break;
+        case "view_cast":
+          handlers.view_cast({ hash: String(p.hash ?? "") });
+          break;
+        case "view_profile":
+          handlers.view_profile({ fid: Number(p.fid ?? 0) });
+          break;
+        case "compose_cast":
+          handlers.compose_cast({
+            text: p.text ? String(p.text) : undefined,
+            channelKey: p.channelKey ? String(p.channelKey) : undefined,
+            embeds: Array.isArray(p.embeds)
+              ? (p.embeds as string[])
+              : undefined,
+          });
+          break;
+        case "view_token":
+          handlers.view_token({ token: String(p.token ?? "") });
+          break;
+        case "send_token":
+          handlers.send_token({
+            token: String(p.token ?? ""),
+            amount: p.amount ? String(p.amount) : undefined,
+            recipientFid: p.recipientFid ? Number(p.recipientFid) : undefined,
+            recipientAddress: p.recipientAddress
+              ? String(p.recipientAddress)
+              : undefined,
+          });
+          break;
+        case "swap_token":
+          handlers.swap_token({
+            sellToken: p.sellToken ? String(p.sellToken) : undefined,
+            buyToken: p.buyToken ? String(p.buyToken) : undefined,
+          });
+          break;
+        default:
+          break;
+      }
+    },
+    [handlers],
+  );
+
+  return (
+    <div style={{ position: "relative", width: "100%" }}>
+      {showConfetti && <ConfettiOverlay />}
+      <SnapLoadingOverlay
+        appearance={appearance}
+        accentHex={accentHex}
+        active={loading}
+      />
+
+      <div style={previewSurfaceStyle}>
+        <SnapPreviewAccentProvider
+          pageAccent={snap.theme?.accent}
+          appearance={appearance}
+        >
+          <SnapCatalogView
+            key={pageKey}
+            spec={spec}
+            state={initialState}
+            loading={false}
+            onStateChange={(changes) => {
+              applyStatePaths(stateRef.current, changes);
+            }}
+            onAction={handleAction}
+          />
+        </SnapPreviewAccentProvider>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,50 @@
+"use client";
+
+import { SnapViewCore } from "../snap-view-core";
+import type { SnapPage, SnapActionHandlers } from "../index";
+
+export function SnapViewV1({
+  snap,
+  handlers,
+  loading = false,
+  appearance = "dark",
+}: {
+  snap: SnapPage;
+  handlers: SnapActionHandlers;
+  loading?: boolean;
+  appearance?: "light" | "dark";
+}) {
+  return (
+    <SnapViewCore
+      snap={snap}
+      handlers={handlers}
+      loading={loading}
+      appearance={appearance}
+    />
+  );
+}
+
+export function SnapCardV1({
+  snap,
+  handlers,
+  loading = false,
+  appearance = "dark",
+  maxWidth = 480,
+}: {
+  snap: SnapPage;
+  handlers: SnapActionHandlers;
+  loading?: boolean;
+  appearance?: "light" | "dark";
+  maxWidth?: number;
+}) {
+  return (
+    <div style={{ position: "relative", width: "100%", maxWidth }}>
+      <SnapViewV1
+        snap={snap}
+        handlers={handlers}
+        loading={loading}
+        appearance={appearance}
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,168 @@
+"use client";
+
+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 type { SnapPage, SnapActionHandlers } from "../index";
+
+const SNAP_MAX_HEIGHT = 500;
+const SNAP_WARNING_HEIGHT = 700;
+
+// ─── Default validation error fallback ────────────────
+
+function SnapValidationFallback({
+  appearance,
+  message,
+}: {
+  appearance: "light" | "dark";
+  message?: string;
+}) {
+  const isDark = appearance === "dark";
+  return (
+    <div
+      style={{
+        width: "100%",
+        padding: 16,
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        color: isDark ? "rgba(255,255,255,0.5)" : "rgba(0,0,0,0.4)",
+        fontSize: 14,
+      }}
+    >
+      <span>{message ? `Unable to render snap: ${message}` : "Unable to render snap"}</span>
+    </div>
+  );
+}
+
+// ─── SnapViewV2 ──────────────────────────────────────
+
+export function SnapViewV2({
+  snap,
+  handlers,
+  loading = false,
+  appearance = "dark",
+  onValidationError,
+  validationErrorFallback,
+}: {
+  snap: SnapPage;
+  handlers: SnapActionHandlers;
+  loading?: boolean;
+  appearance?: "light" | "dark";
+  onValidationError?: (result: ValidationResult) => void;
+  validationErrorFallback?: ReactNode;
+}) {
+  const validation = useMemo(() => validateSnapResponse(snap), [snap]);
+  const valid = validation.valid;
+  const validationMessage = validation.issues[0]?.message;
+
+  useEffect(() => {
+    if (!valid) {
+      if (onValidationError) {
+        onValidationError(validation);
+      } else {
+        // eslint-disable-next-line no-console
+        console.warn("[Snap] validation issues:", validation.issues);
+      }
+    }
+  }, [valid, validation, onValidationError]);
+
+  if (!valid) {
+    if (validationErrorFallback === null) return null;
+    return <>{validationErrorFallback ?? <SnapValidationFallback appearance={appearance} message={validationMessage} />}</>;
+  }
+
+  return (
+    <SnapViewCore
+      snap={snap}
+      handlers={handlers}
+      loading={loading}
+      appearance={appearance}
+    />
+  );
+}
+
+// ─── SnapCardV2 ──────────────────────────────────────
+
+export function SnapCardV2({
+  snap,
+  handlers,
+  loading = false,
+  appearance = "dark",
+  maxWidth = 480,
+  showOverflowWarning = false,
+  onValidationError,
+  validationErrorFallback,
+}: {
+  snap: SnapPage;
+  handlers: SnapActionHandlers;
+  loading?: boolean;
+  appearance?: "light" | "dark";
+  maxWidth?: number;
+  showOverflowWarning?: boolean;
+  onValidationError?: (result: ValidationResult) => void;
+  validationErrorFallback?: ReactNode;
+}) {
+  const maxHeight = showOverflowWarning ? SNAP_WARNING_HEIGHT : SNAP_MAX_HEIGHT;
+  const bg = appearance === "dark" ? "rgba(0,0,0,0.85)" : "rgba(255,255,255,0.9)";
+
+  return (
+    <div
+      style={{
+        position: "relative",
+        width: "100%",
+        maxWidth,
+        maxHeight,
+        overflow: "hidden",
+      }}
+    >
+      <SnapViewV2
+        snap={snap}
+        handlers={handlers}
+        loading={loading}
+        appearance={appearance}
+        onValidationError={onValidationError}
+        validationErrorFallback={validationErrorFallback}
+      />
+      {showOverflowWarning && (
+        <div
+          style={{
+            position: "absolute",
+            top: SNAP_MAX_HEIGHT,
+            left: 0,
+            right: 0,
+            bottom: 0,
+            pointerEvents: "none",
+            zIndex: 10,
+          }}
+        >
+          <div style={{ borderTop: "1px dashed rgba(255,100,100,0.6)", position: "relative" }}>
+            <span
+              style={{
+                position: "absolute",
+                top: -10,
+                right: 0,
+                fontSize: 10,
+                fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
+                color: "rgba(255,100,100,0.7)",
+                background: bg,
+                padding: "1px 4px",
+                borderRadius: 3,
+              }}
+            >
+              {SNAP_MAX_HEIGHT}px
+            </span>
+          </div>
+          <div
+            style={{
+              height: "100%",
+              background:
+                "repeating-linear-gradient(-45deg, transparent, transparent 8px, rgba(255,100,100,0.06) 8px, rgba(255,100,100,0.06) 16px)",
+            }}
+          />
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -2,16 +2,29 @@ declare const __DEV__: boolean;
 
 import type { ComponentRenderProps } from "@json-render/react-native";
 import { Pressable, StyleSheet, Text, View } from "react-native";
+import { ExternalLink } from "lucide-react-native";
 import { useSnapPalette } from "../use-snap-palette";
 import { useSnapTheme } from "../theme";
 import { ICON_MAP } from "./snap-icon";
 
+function isExternalLinkAction(
+  on: Record<string, unknown> | undefined,
+): boolean {
+  if (!on) return false;
+  const press = on.press as
+    | { action?: string; params?: Record<string, unknown> }
+    | undefined;
+  if (!press || press.action !== "open_url") return false;
+  return press.params?.isSnap !== true;
+}
+
 export function SnapActionButton({
-  element: { props },
+  element,
   emit,
 }: ComponentRenderProps<Record<string, unknown>>) {
   const { accentHex } = useSnapPalette();
   const { colors } = useSnapTheme();
+  const { props } = element;
   const label = String(props.label ?? "Action");
   const variant = String(props.variant ?? "secondary");
   const isPrimary = variant === "primary";
@@ -20,6 +33,9 @@ export function SnapActionButton({
   const textColor = isPrimary ? "#fff" : colors.text;
   const iconColor = isPrimary ? "#fff" : colors.text;
 
+  const on = (element as unknown as { on?: Record<string, unknown> }).on;
+  const showExternalIcon = isExternalLinkAction(on);
+
   return (
     <View style={styles.outer}>
       <Pressable
@@ -43,12 +59,18 @@ export function SnapActionButton({
           })();
         }}
       >
-        {iconName && ICON_MAP[iconName] ? (
-          (() => { const I = ICON_MAP[iconName]!; return <I size={16} color={iconColor} />; })()
-        ) : null}
+        {iconName && ICON_MAP[iconName]
+          ? (() => {
+              const I = ICON_MAP[iconName]!;
+              return <I size={16} color={iconColor} />;
+            })()
+          : null}
         <Text style={{ color: textColor, fontSize: 14, fontWeight: "600" }}>
           {label}
         </Text>
+        {showExternalIcon ? (
+          <ExternalLink size={14} color={iconColor} style={{ opacity: 0.6 }} />
+        ) : null}
       </Pressable>
     </View>
   );

package/src/react-native/components/snap-badge.tsx

@@ -22,17 +22,17 @@ export function SnapBadge({
       style={[
         styles.badge,
         isFilled
-          ? { backgroundColor: resolvedColor, borderColor: resolvedColor }
+          ? { backgroundColor: resolvedColor + "20", borderColor: "transparent" }
           : { borderColor: resolvedColor },
       ]}
     >
       {Icon && (
-        <Icon size={12} color={isFilled ? "#fff" : resolvedColor} />
+        <Icon size={12} color={resolvedColor} />
       )}
       <Text
         style={[
           styles.label,
-          { color: isFilled ? "#fff" : resolvedColor },
+          { color: resolvedColor },
         ]}
       >
         {label}