@farcaster/snap 2.6.4 → 2.7.1

package/src/react/index.tsx

@@ -4,6 +4,7 @@ import type { Spec } from "@json-render/core";
 import type { ReactNode } from "react";
 import type { ValidationResult } from "../validator.js";
 import { SPEC_VERSION_2 } from "../constants";
+import type { SnapRenderState } from "../render-state";
 import { SnapCardV1 } from "./v1/snap-view";
 import { SnapCardV2 } from "./v2/snap-view";
 
@@ -24,6 +25,29 @@ export type SnapPage = {
   ui: Spec;
 };
 
+export type SnapSendTransactionParams = {
+  chainId: string;
+  to: string;
+  data?: string;
+  value?: string;
+  gas?: string;
+  gasPrice?: string;
+  maxFeePerGas?: string;
+  maxPriorityFeePerGas?: string;
+};
+
+export type SnapSendCallsParams = {
+  version?: "1.0";
+  chainId: string;
+  atomicRequired?: boolean;
+  id?: string;
+  calls: Array<{
+    to?: string;
+    data?: string;
+    value?: string;
+  }>;
+};
+
 export type SnapActionHandlers = {
   submit: (target: string, inputs: Record<string, JsonValue>) => void;
   open_url: (target: string) => void;
@@ -44,8 +68,12 @@ export type SnapActionHandlers = {
     recipientAddress?: string;
   }) => void;
   swap_token: (params: { sellToken?: string; buyToken?: string }) => void;
+  send_transaction?: (params: SnapSendTransactionParams) => void;
+  send_calls?: (params: SnapSendCallsParams) => void;
 };
 
+export type { SnapRenderState };
+
 // ─── SnapCard ────────────────────────────────────────
 
 export function SnapCard({
@@ -60,6 +88,8 @@ export function SnapCard({
   actionError,
   plain = false,
   loadingOverlay,
+  initialRenderState,
+  onRenderStateChange,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -76,6 +106,10 @@ export function SnapCard({
   plain?: boolean;
   /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
   loadingOverlay?: ReactNode;
+  /** JSON-render local state used to seed this presenter mount. */
+  initialRenderState?: SnapRenderState;
+  /** Called with the full JSON-render local state after state changes. */
+  onRenderStateChange?: (state: SnapRenderState) => void;
 }) {
   if (snap.version === SPEC_VERSION_2) {
     return (
@@ -91,6 +125,8 @@ export function SnapCard({
         actionError={actionError}
         plain={plain}
         loadingOverlay={loadingOverlay}
+        initialRenderState={initialRenderState}
+        onRenderStateChange={onRenderStateChange}
       />
     );
   }
@@ -105,6 +141,8 @@ export function SnapCard({
       actionError={actionError}
       plain={plain}
       loadingOverlay={loadingOverlay}
+      initialRenderState={initialRenderState}
+      onRenderStateChange={onRenderStateChange}
     />
   );
 }

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

@@ -7,6 +7,14 @@ import { SnapPreviewAccentProvider } from "./accent-context";
 import { SnapVersionProvider } from "./snap-version-context";
 import { resolveSnapPaletteHex } from "./lib/resolve-palette-hex";
 import { snapPreviewPrimaryCssProperties } from "./lib/preview-primary-css";
+import {
+  applyStatePaths,
+  buildInitialRenderState,
+  cloneSnapRenderState,
+  getUnpresentedSnapEffects,
+  markSnapEffectsPresented,
+  type SnapRenderState,
+} from "../render-state";
 import {
   type CSSProperties,
   type ReactNode,
@@ -18,45 +26,14 @@ import {
 } from "react";
 import type { JsonValue, SnapActionHandlers, SnapPage } from "./index";
 
-// ─── Internal helpers ──────────────────────────────────
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object"
+    ? (value as Record<string, unknown>)
+    : {};
+}
 
-export function applyStatePaths(
-  model: Record<string, unknown>,
-  changes:
-    | { path: string; value: unknown }[]
-    | Record<string, unknown>
-    | null
-    | undefined,
-): void {
-  if (!changes) return;
-  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;
-      }
-    }
-  }
+function optionalString(value: unknown): string | undefined {
+  return value ? String(value) : undefined;
 }
 
 function withDefaultElementProps(spec: Spec): Spec {
@@ -137,7 +114,18 @@ function ConfettiOverlay() {
       }}
     >
       {pieces.map(
-        ({ id, left, delay, duration, color, size, rotation, isCircle, driftX, driftMid }) => (
+        ({
+          id,
+          left,
+          delay,
+          duration,
+          color,
+          size,
+          rotation,
+          isCircle,
+          driftX,
+          driftMid,
+        }) => (
           <div
             key={id}
             style={
@@ -179,8 +167,7 @@ function FireworksOverlay() {
         y: 10 + Math.random() * 50,
         delay: b * 0.5 + Math.random() * 0.2,
         particles: Array.from({ length: 24 }, (_, p) => {
-          const angle =
-            (p / 24) * Math.PI * 2 + (Math.random() - 0.5) * 0.2;
+          const angle = (p / 24) * Math.PI * 2 + (Math.random() - 0.5) * 0.2;
           const dist = 55 + Math.random() * 60;
           return {
             id: p,
@@ -288,9 +275,7 @@ export function SnapLoadingOverlay({
         zIndex: 10,
         background: tint,
         backdropFilter: active ? "blur(10px) saturate(1.05)" : "none",
-        WebkitBackdropFilter: 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",
@@ -349,6 +334,8 @@ export function SnapViewCore({
   loading = false,
   appearance = "dark",
   loadingOverlay,
+  initialRenderState,
+  onRenderStateChange,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -359,21 +346,24 @@ export function SnapViewCore({
    * the built-in spinner + backdrop is used. Pass `null` to render nothing.
    */
   loadingOverlay?: ReactNode;
+  initialRenderState?: SnapRenderState;
+  onRenderStateChange?: (state: SnapRenderState) => void;
 }) {
   const spec = useMemo(() => withDefaultElementProps(snap.ui), [snap.ui]);
-  const initialState = useMemo(() => spec.state ?? { inputs: {} }, [spec]);
+  const initialState = useMemo(
+    () =>
+      buildInitialRenderState({
+        specState: spec.state,
+        initialRenderState,
+        themeAccent: snap.theme?.accent,
+      }),
+    [initialRenderState, spec.state, snap.theme?.accent],
+  );
 
   const stateRef = useRef<Record<string, unknown>>(initialState);
 
   useEffect(() => {
-    stateRef.current = {
-      inputs: {
-        ...((initialState.inputs ?? {}) as Record<string, unknown>),
-      },
-      theme: {
-        ...((initialState.theme ?? {}) as Record<string, unknown>),
-      },
-    };
+    stateRef.current = cloneSnapRenderState(initialState);
   }, [initialState]);
 
   useEffect(() => {
@@ -389,14 +379,58 @@ export function SnapViewCore({
     setPageKey((k) => k + 1);
   }, [spec]);
 
-  const showConfetti = snap.effects?.includes("confetti") ?? false;
-  const showFireworks = snap.effects?.includes("fireworks") ?? false;
-  const [confettiKey, setConfettiKey] = useState(0);
-  const [fireworksKey, setFireworksKey] = useState(0);
+  const effectSignature = snap.effects?.join("\u0000") ?? "";
+  const snapEffects = useMemo(
+    () => (effectSignature ? effectSignature.split("\u0000") : []),
+    [effectSignature],
+  );
+  const showConfetti = snapEffects.includes("confetti");
+  const showFireworks = snapEffects.includes("fireworks");
+  const [effectRunKeys, setEffectRunKeys] = useState({
+    confetti: 0,
+    fireworks: 0,
+  });
+  const onRenderStateChangeRef = useRef(onRenderStateChange);
+  useEffect(() => {
+    onRenderStateChangeRef.current = onRenderStateChange;
+  }, [onRenderStateChange]);
   useEffect(() => {
-    if (showConfetti) setConfettiKey((k) => k + 1);
-    if (showFireworks) setFireworksKey((k) => k + 1);
-  }, [showConfetti, showFireworks, snap]);
+    const effectsToPresent = getUnpresentedSnapEffects(
+      stateRef.current,
+      snapEffects,
+    );
+
+    if (effectsToPresent.length === 0) {
+      setEffectRunKeys((current) => {
+        const next = {
+          confetti: showConfetti ? current.confetti : 0,
+          fireworks: showFireworks ? current.fireworks : 0,
+        };
+        return next.confetti === current.confetti &&
+          next.fireworks === current.fireworks
+          ? current
+          : next;
+      });
+      return;
+    }
+
+    if (markSnapEffectsPresented(stateRef.current, effectsToPresent)) {
+      onRenderStateChangeRef.current?.(cloneSnapRenderState(stateRef.current));
+    }
+
+    setEffectRunKeys((current) => ({
+      confetti: effectsToPresent.includes("confetti")
+        ? current.confetti + 1
+        : showConfetti
+          ? current.confetti
+          : 0,
+      fireworks: effectsToPresent.includes("fireworks")
+        ? current.fireworks + 1
+        : showFireworks
+          ? current.fireworks
+          : 0,
+    }));
+  }, [initialState, showConfetti, showFireworks, snapEffects]);
 
   const accentName = snap.theme?.accent ?? "purple";
 
@@ -469,6 +503,39 @@ export function SnapViewCore({
             buyToken: p.buyToken ? String(p.buyToken) : undefined,
           });
           break;
+        case "send_transaction":
+          handlers.send_transaction?.({
+            chainId: String(p.chainId ?? ""),
+            to: String(p.to ?? ""),
+            data: optionalString(p.data),
+            value: optionalString(p.value),
+            gas: optionalString(p.gas),
+            gasPrice: optionalString(p.gasPrice),
+            maxFeePerGas: optionalString(p.maxFeePerGas),
+            maxPriorityFeePerGas: optionalString(p.maxPriorityFeePerGas),
+          });
+          break;
+        case "send_calls":
+          handlers.send_calls?.({
+            version: p.version === "1.0" ? "1.0" : undefined,
+            chainId: String(p.chainId ?? ""),
+            atomicRequired:
+              typeof p.atomicRequired === "boolean"
+                ? p.atomicRequired
+                : undefined,
+            id: optionalString(p.id),
+            calls: Array.isArray(p.calls)
+              ? p.calls.map((call) => {
+                  const c = asRecord(call);
+                  return {
+                    to: optionalString(c.to),
+                    data: optionalString(c.data),
+                    value: optionalString(c.value),
+                  };
+                })
+              : [],
+          });
+          break;
         default:
           break;
       }
@@ -478,8 +545,12 @@ export function SnapViewCore({
 
   return (
     <div style={{ position: "relative", width: "100%" }}>
-      {showConfetti && <ConfettiOverlay key={confettiKey} />}
-      {showFireworks && <FireworksOverlay key={fireworksKey} />}
+      {showConfetti && effectRunKeys.confetti > 0 && (
+        <ConfettiOverlay key={effectRunKeys.confetti} />
+      )}
+      {showFireworks && effectRunKeys.fireworks > 0 && (
+        <FireworksOverlay key={effectRunKeys.fireworks} />
+      )}
       {loadingOverlay === undefined ? (
         <SnapLoadingOverlay
           appearance={appearance}
@@ -503,6 +574,7 @@ export function SnapViewCore({
               loading={false}
               onStateChange={(changes) => {
                 applyStatePaths(stateRef.current, changes);
+                onRenderStateChange?.(cloneSnapRenderState(stateRef.current));
               }}
               onAction={handleAction}
             />

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

@@ -3,7 +3,7 @@
 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";
+import type { SnapActionHandlers, SnapPage, SnapRenderState } from "../index";
 
 const SNAP_MAX_HEIGHT = 500;
 
@@ -13,6 +13,8 @@ export function SnapViewV1({
   loading = false,
   appearance = "dark",
   loadingOverlay,
+  initialRenderState,
+  onRenderStateChange,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -20,6 +22,8 @@ export function SnapViewV1({
   appearance?: "light" | "dark";
   /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
   loadingOverlay?: ReactNode;
+  initialRenderState?: SnapRenderState;
+  onRenderStateChange?: (state: SnapRenderState) => void;
 }) {
   return (
     <SnapViewCore
@@ -28,6 +32,8 @@ export function SnapViewV1({
       loading={loading}
       appearance={appearance}
       loadingOverlay={loadingOverlay}
+      initialRenderState={initialRenderState}
+      onRenderStateChange={onRenderStateChange}
     />
   );
 }
@@ -41,6 +47,8 @@ export function SnapCardV1({
   actionError,
   plain = false,
   loadingOverlay,
+  initialRenderState,
+  onRenderStateChange,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -51,6 +59,10 @@ export function SnapCardV1({
   plain?: boolean;
   /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
   loadingOverlay?: ReactNode;
+  /** JSON-render local state used to seed this presenter mount. */
+  initialRenderState?: SnapRenderState;
+  /** Called with the full JSON-render local state after state changes. */
+  onRenderStateChange?: (state: SnapRenderState) => void;
 }) {
   const isDark = appearance === "dark";
   const borderColor = isDark ? "rgba(255,255,255,0.1)" : "rgba(0,0,0,0.1)";
@@ -135,6 +147,8 @@ export function SnapCardV1({
               loading={loading}
               appearance={appearance}
               loadingOverlay={null}
+              initialRenderState={initialRenderState}
+              onRenderStateChange={onRenderStateChange}
             />
           </div>
         </div>

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

@@ -5,7 +5,7 @@ import { validateSnapResponse } from "../../validator.js";
 import type { ValidationResult } from "../../validator.js";
 import { SnapViewCore, SnapLoadingOverlay } from "../snap-view-core";
 import { resolveSnapPaletteHex } from "../lib/resolve-palette-hex";
-import type { SnapPage, SnapActionHandlers } from "../index";
+import type { SnapActionHandlers, SnapPage, SnapRenderState } from "../index";
 
 const SNAP_MAX_HEIGHT = 500;
 const SNAP_WARNING_HEIGHT = 700;
@@ -48,6 +48,8 @@ export function SnapViewV2({
   onValidationError,
   validationErrorFallback,
   loadingOverlay,
+  initialRenderState,
+  onRenderStateChange,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -57,6 +59,8 @@ export function SnapViewV2({
   validationErrorFallback?: ReactNode;
   /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
   loadingOverlay?: ReactNode;
+  initialRenderState?: SnapRenderState;
+  onRenderStateChange?: (state: SnapRenderState) => void;
 }) {
   const validation = useMemo(() => validateSnapResponse(snap), [snap]);
   const valid = validation.valid;
@@ -85,6 +89,8 @@ export function SnapViewV2({
       loading={loading}
       appearance={appearance}
       loadingOverlay={loadingOverlay}
+      initialRenderState={initialRenderState}
+      onRenderStateChange={onRenderStateChange}
     />
   );
 }
@@ -103,6 +109,8 @@ export function SnapCardV2({
   actionError,
   plain = false,
   loadingOverlay,
+  initialRenderState,
+  onRenderStateChange,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -116,6 +124,10 @@ export function SnapCardV2({
   plain?: boolean;
   /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
   loadingOverlay?: ReactNode;
+  /** JSON-render local state used to seed this presenter mount. */
+  initialRenderState?: SnapRenderState;
+  /** Called with the full JSON-render local state after state changes. */
+  onRenderStateChange?: (state: SnapRenderState) => void;
 }) {
   const isDark = appearance === "dark";
   const bg = isDark ? "rgba(0,0,0,0.85)" : "rgba(255,255,255,0.9)";
@@ -208,6 +220,8 @@ export function SnapCardV2({
               onValidationError={onValidationError}
               validationErrorFallback={validationErrorFallback}
               loadingOverlay={null}
+              initialRenderState={initialRenderState}
+              onRenderStateChange={onRenderStateChange}
             />
           </div>
         </div>

package/src/react-native/index.tsx

@@ -2,7 +2,12 @@ import type { ReactNode } from "react";
 import type { ValidationResult } from "@farcaster/snap";
 import { SPEC_VERSION_2 } from "@farcaster/snap";
 import type { SnapNativeColors } from "./theme";
-import type { JsonValue, SnapPage, SnapActionHandlers } from "./types";
+import type {
+  JsonValue,
+  SnapActionHandlers,
+  SnapPage,
+  SnapRenderState,
+} from "./types";
 import { useSnapTheme } from "./theme";
 import { hexToRgba } from "./use-snap-palette";
 import { SnapCardV1 } from "./v1/snap-view";
@@ -10,7 +15,12 @@ import { SnapCardV2 } from "./v2/snap-view";
 
 // ─── Public types ──────────────────────────────────────
 
-export type { JsonValue, SnapPage, SnapActionHandlers } from "./types";
+export type {
+  JsonValue,
+  SnapActionHandlers,
+  SnapPage,
+  SnapRenderState,
+} from "./types";
 
 // ─── Re-exports ───────────────────────────────────────
 
@@ -35,6 +45,8 @@ export function SnapCard({
   forceExpanded,
   expandButtonLabel,
   onExpandPress,
+  initialRenderState,
+  onRenderStateChange,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -61,6 +73,10 @@ export function SnapCard({
   expandButtonLabel?: string;
   /** Called from the collapsed expand button instead of toggling internal state. */
   onExpandPress?: () => void;
+  /** JSON-render local state used to seed this presenter mount. */
+  initialRenderState?: SnapRenderState;
+  /** Called with the full JSON-render local state after state changes. */
+  onRenderStateChange?: (state: SnapRenderState) => void;
 }) {
   if (snap.version === SPEC_VERSION_2) {
     return (
@@ -80,6 +96,8 @@ export function SnapCard({
         forceExpanded={forceExpanded}
         expandButtonLabel={expandButtonLabel}
         onExpandPress={onExpandPress}
+        initialRenderState={initialRenderState}
+        onRenderStateChange={onRenderStateChange}
       />
     );
   }
@@ -98,6 +116,8 @@ export function SnapCard({
       forceExpanded={forceExpanded}
       expandButtonLabel={expandButtonLabel}
       onExpandPress={onExpandPress}
+      initialRenderState={initialRenderState}
+      onRenderStateChange={onRenderStateChange}
     />
   );
 }