@farcaster/snap 2.6.4 → 2.7.0

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}
     />
   );
 }

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

@@ -20,49 +20,16 @@ import {
   PALETTE_DARK_HEX,
   type PaletteColor,
 } from "@farcaster/snap";
+import {
+  applyStatePaths,
+  buildInitialRenderState,
+  cloneSnapRenderState,
+  getUnpresentedSnapEffects,
+  markSnapEffectsPresented,
+  type SnapRenderState,
+} from "../render-state";
 import type { SnapPage, SnapActionHandlers, JsonValue } from "./types";
 
-// ─── Shared helpers ──────────────────────────────────
-
-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 withDefaultElementProps(spec: Spec): Spec {
   if (!spec || typeof spec !== "object" || !("elements" in spec)) return spec;
   const elements = spec.elements as unknown as Record<
@@ -106,6 +73,8 @@ export function SnapViewCoreInner({
   handlers,
   loading = false,
   loadingOverlay,
+  initialRenderState,
+  onRenderStateChange,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -115,6 +84,8 @@ export function SnapViewCoreInner({
    * the built-in ActivityIndicator overlay is used. Pass `null` to render nothing.
    */
   loadingOverlay?: ReactNode;
+  initialRenderState?: SnapRenderState;
+  onRenderStateChange?: (state: SnapRenderState) => void;
 }) {
   const { mode } = useSnapTheme();
   const spec = useMemo(
@@ -124,28 +95,19 @@ export function SnapViewCoreInner({
   const accentHex = resolveAccentHex(snap.theme?.accent, mode);
 
   const initialState = useMemo(
-    () => ({
-      ...(spec.state ?? {}),
-      inputs: { ...((spec.state?.inputs ?? {}) as Record<string, unknown>) },
-      theme: {
-        ...((spec.state?.theme ?? {}) as Record<string, unknown>),
-        ...(snap.theme ? { accent: snap.theme.accent } : {}),
-      },
-    }),
-    [spec, snap.theme],
+    () =>
+      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(() => {
@@ -161,14 +123,58 @@ export function SnapViewCoreInner({
     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 handlersRef = useRef(handlers);
   handlersRef.current = handlers;
@@ -229,16 +235,13 @@ export function SnapViewCoreInner({
 
   return (
     <View style={styles.container}>
-      {loading
-        ? loadingOverlay === undefined
-          ? (
-            <SnapLoadingOverlay
-              appearance={mode}
-              accentHex={accentHex}
-            />
-          )
-          : loadingOverlay
-        : null}
+      {loading ? (
+        loadingOverlay === undefined ? (
+          <SnapLoadingOverlay appearance={mode} accentHex={accentHex} />
+        ) : (
+          loadingOverlay
+        )
+      ) : null}
       <SnapVersionProvider value={snap.version === "2.0" ? "2.0" : "1.0"}>
         <SnapCatalogView
           key={pageKey}
@@ -247,12 +250,17 @@ export function SnapViewCoreInner({
           loading={false}
           onStateChange={(changes) => {
             applyStatePaths(stateRef.current, changes);
+            onRenderStateChange?.(cloneSnapRenderState(stateRef.current));
           }}
           onAction={handleAction}
         />
       </SnapVersionProvider>
-      {showConfetti && <ConfettiOverlay key={confettiKey} />}
-      {showFireworks && <FireworksOverlay key={fireworksKey} />}
+      {showConfetti && effectRunKeys.confetti > 0 && (
+        <ConfettiOverlay key={effectRunKeys.confetti} />
+      )}
+      {showFireworks && effectRunKeys.fireworks > 0 && (
+        <FireworksOverlay key={effectRunKeys.fireworks} />
+      )}
     </View>
   );
 }
@@ -270,9 +278,7 @@ export function SnapLoadingOverlay({
         styles.overlay,
         {
           backgroundColor:
-            appearance === "dark"
-              ? "rgba(0,0,0,0.1)"
-              : "rgba(255,255,255,0.2)",
+            appearance === "dark" ? "rgba(0,0,0,0.1)" : "rgba(255,255,255,0.2)",
         },
       ]}
     >

package/src/react-native/types.ts

@@ -1,4 +1,7 @@
 import type { Spec } from "@json-render/core";
+import type { SnapRenderState } from "../render-state";
+
+export type { SnapRenderState };
 
 export type JsonValue =
   | string

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

@@ -6,7 +6,7 @@ import {
   SnapViewCoreInner,
   resolveAccentHex,
 } from "../snap-view-core";
-import type { SnapPage, SnapActionHandlers } from "../types";
+import type { SnapActionHandlers, SnapPage, SnapRenderState } from "../types";
 import { getSnapExpansionState } from "../expand-state";
 
 // ─── SnapViewV1 (no validation) ──────────────────────
@@ -16,11 +16,15 @@ export function SnapViewV1Inner({
   handlers,
   loading = false,
   loadingOverlay,
+  initialRenderState,
+  onRenderStateChange,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
   loading?: boolean;
   loadingOverlay?: ReactNode;
+  initialRenderState?: SnapRenderState;
+  onRenderStateChange?: (state: SnapRenderState) => void;
 }) {
   return (
     <SnapViewCoreInner
@@ -28,6 +32,8 @@ export function SnapViewV1Inner({
       handlers={handlers}
       loading={loading}
       loadingOverlay={loadingOverlay}
+      initialRenderState={initialRenderState}
+      onRenderStateChange={onRenderStateChange}
     />
   );
 }
@@ -39,6 +45,8 @@ export function SnapViewV1({
   appearance = "dark",
   colors,
   loadingOverlay,
+  initialRenderState,
+  onRenderStateChange,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -47,6 +55,8 @@ export function SnapViewV1({
   colors?: Partial<SnapNativeColors>;
   /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
   loadingOverlay?: ReactNode;
+  initialRenderState?: SnapRenderState;
+  onRenderStateChange?: (state: SnapRenderState) => void;
 }) {
   return (
     <SnapThemeProvider appearance={appearance} colors={colors}>
@@ -55,6 +65,8 @@ export function SnapViewV1({
         handlers={handlers}
         loading={loading}
         loadingOverlay={loadingOverlay}
+        initialRenderState={initialRenderState}
+        onRenderStateChange={onRenderStateChange}
       />
     </SnapThemeProvider>
   );
@@ -74,6 +86,8 @@ function SnapCardV1Inner({
   forceExpanded,
   expandButtonLabel,
   onExpandPress,
+  initialRenderState,
+  onRenderStateChange,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -86,6 +100,8 @@ function SnapCardV1Inner({
   forceExpanded?: boolean;
   expandButtonLabel?: string;
   onExpandPress?: () => void;
+  initialRenderState?: SnapRenderState;
+  onRenderStateChange?: (state: SnapRenderState) => void;
 }) {
   const { colors, mode } = useSnapTheme();
   const accentHex = resolveAccentHex(snap.theme?.accent, mode);
@@ -148,6 +164,8 @@ function SnapCardV1Inner({
                 handlers={handlers}
                 loading={loading}
                 loadingOverlay={null}
+                initialRenderState={initialRenderState}
+                onRenderStateChange={onRenderStateChange}
               />
             </View>
           </View>
@@ -223,6 +241,8 @@ export function SnapCardV1({
   forceExpanded,
   expandButtonLabel,
   onExpandPress,
+  initialRenderState,
+  onRenderStateChange,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -240,6 +260,10 @@ export function SnapCardV1({
   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;
 }) {
   return (
     <SnapThemeProvider appearance={appearance} colors={colors}>
@@ -255,6 +279,8 @@ export function SnapCardV1({
         forceExpanded={forceExpanded}
         expandButtonLabel={expandButtonLabel}
         onExpandPress={onExpandPress}
+        initialRenderState={initialRenderState}
+        onRenderStateChange={onRenderStateChange}
       />
     </SnapThemeProvider>
   );

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

@@ -11,7 +11,7 @@ import {
   validateSnapResponse,
   type ValidationResult,
 } from "@farcaster/snap";
-import type { SnapPage, SnapActionHandlers } from "../types";
+import type { SnapActionHandlers, SnapPage, SnapRenderState } from "../types";
 import { getSnapExpansionState, SNAP_MAX_HEIGHT } from "../expand-state";
 
 // ─── Constants ───────────────────────────────────────
@@ -53,6 +53,8 @@ export function SnapViewV2Inner({
   onValidationError,
   validationErrorFallback,
   loadingOverlay,
+  initialRenderState,
+  onRenderStateChange,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -60,6 +62,8 @@ export function SnapViewV2Inner({
   onValidationError?: (result: ValidationResult) => void;
   validationErrorFallback?: ReactNode;
   loadingOverlay?: ReactNode;
+  initialRenderState?: SnapRenderState;
+  onRenderStateChange?: (state: SnapRenderState) => void;
 }) {
   const validation = useMemo(() => validateSnapResponse(snap), [snap]);
   const valid = validation.valid;
@@ -89,6 +93,8 @@ export function SnapViewV2Inner({
       handlers={handlers}
       loading={loading}
       loadingOverlay={loadingOverlay}
+      initialRenderState={initialRenderState}
+      onRenderStateChange={onRenderStateChange}
     />
   );
 }
@@ -102,6 +108,8 @@ export function SnapViewV2({
   onValidationError,
   validationErrorFallback,
   loadingOverlay,
+  initialRenderState,
+  onRenderStateChange,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -112,6 +120,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;
 }) {
   return (
     <SnapThemeProvider appearance={appearance} colors={colors}>
@@ -122,6 +132,8 @@ export function SnapViewV2({
         onValidationError={onValidationError}
         validationErrorFallback={validationErrorFallback}
         loadingOverlay={loadingOverlay}
+        initialRenderState={initialRenderState}
+        onRenderStateChange={onRenderStateChange}
       />
     </SnapThemeProvider>
   );
@@ -144,6 +156,8 @@ function SnapCardV2Inner({
   forceExpanded,
   expandButtonLabel,
   onExpandPress,
+  initialRenderState,
+  onRenderStateChange,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -159,6 +173,8 @@ function SnapCardV2Inner({
   forceExpanded?: boolean;
   expandButtonLabel?: string;
   onExpandPress?: () => void;
+  initialRenderState?: SnapRenderState;
+  onRenderStateChange?: (state: SnapRenderState) => void;
 }) {
   const { colors, mode } = useSnapTheme();
   const accentHex = resolveAccentHex(snap.theme?.accent, mode);
@@ -188,6 +204,8 @@ function SnapCardV2Inner({
       onValidationError={onValidationError}
       validationErrorFallback={validationErrorFallback}
       loadingOverlay={null}
+      initialRenderState={initialRenderState}
+      onRenderStateChange={onRenderStateChange}
     />
   );
 
@@ -375,6 +393,8 @@ export function SnapCardV2({
   forceExpanded,
   expandButtonLabel,
   onExpandPress,
+  initialRenderState,
+  onRenderStateChange,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -395,6 +415,10 @@ export function SnapCardV2({
   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;
 }) {
   return (
     <SnapThemeProvider appearance={appearance} colors={colors}>
@@ -413,6 +437,8 @@ export function SnapCardV2({
         forceExpanded={forceExpanded}
         expandButtonLabel={expandButtonLabel}
         onExpandPress={onExpandPress}
+        initialRenderState={initialRenderState}
+        onRenderStateChange={onRenderStateChange}
       />
     </SnapThemeProvider>
   );