@farcaster/snap 2.6.4 → 2.7.0

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export { SPEC_VERSION, SPEC_VERSION_1, SPEC_VERSION_2, SUPPORTED_SPEC_VERSIONS,
 export { DEFAULT_THEME_ACCENT, PALETTE_COLOR, PALETTE_COLOR_ACCENT, PALETTE_COLOR_VALUES, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, isSnapHexColorString, readableTextOnHex, resolveSnapColorHex, type PaletteColor, } from "./colors.js";
 export { ACTION_TYPE_GET, ACTION_TYPE_POST, snapResponseSchema, payloadSchema, getPayloadSchema, type SnapAction, type SnapGetAction, type SnapContext, type SnapResponse, type SnapHandlerResult, type SnapElementInput, type SnapSpecInput, type SnapFunction, type SnapPayload, type SnapGetPayload, } from "./schemas.js";
 export { validateSnapResponse, type ValidationResult } from "./validator.js";
+export type { SnapRenderState } from "./render-state.js";

package/dist/react/index.d.ts

@@ -1,6 +1,7 @@
 import type { Spec } from "@json-render/core";
 import type { ReactNode } from "react";
 import type { ValidationResult } from "../validator.js";
+import type { SnapRenderState } from "../render-state.js";
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
@@ -42,7 +43,8 @@ export type SnapActionHandlers = {
         buyToken?: string;
     }) => void;
 };
-export declare function SnapCard({ snap, handlers, loading, appearance, maxWidth, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, loadingOverlay, }: {
+export type { SnapRenderState };
+export declare function SnapCard({ snap, handlers, loading, appearance, maxWidth, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, loadingOverlay, initialRenderState, onRenderStateChange, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -58,4 +60,8 @@ export declare function SnapCard({ snap, handlers, loading, appearance, maxWidth
     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;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/react/index.js

@@ -4,9 +4,9 @@ import { SPEC_VERSION_2 } from "../constants.js";
 import { SnapCardV1 } from "./v1/snap-view.js";
 import { SnapCardV2 } from "./v2/snap-view.js";
 // ─── SnapCard ────────────────────────────────────────
-export function SnapCard({ snap, handlers, loading = false, appearance = "dark", maxWidth = 480, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, loadingOverlay, }) {
+export function SnapCard({ snap, handlers, loading = false, appearance = "dark", maxWidth = 480, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, loadingOverlay, initialRenderState, onRenderStateChange, }) {
     if (snap.version === SPEC_VERSION_2) {
-        return (_jsx(SnapCardV2, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, maxWidth: maxWidth, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, plain: plain, loadingOverlay: loadingOverlay }));
+        return (_jsx(SnapCardV2, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, maxWidth: maxWidth, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, plain: plain, loadingOverlay: loadingOverlay, initialRenderState: initialRenderState, onRenderStateChange: onRenderStateChange }));
     }
-    return (_jsx(SnapCardV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, maxWidth: maxWidth, actionError: actionError, plain: plain, loadingOverlay: loadingOverlay }));
+    return (_jsx(SnapCardV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, maxWidth: maxWidth, actionError: actionError, plain: plain, loadingOverlay: loadingOverlay, initialRenderState: initialRenderState, onRenderStateChange: onRenderStateChange }));
 }

package/dist/react/snap-view-core.d.ts

@@ -1,15 +1,12 @@
+import { type SnapRenderState } from "../render-state.js";
 import { type ReactNode } from "react";
 import type { SnapActionHandlers, SnapPage } from "./index.js";
-export declare function applyStatePaths(model: Record<string, unknown>, changes: {
-    path: string;
-    value: unknown;
-}[] | Record<string, unknown> | null | undefined): void;
 export declare function SnapLoadingOverlay({ appearance, accentHex, active, }: {
     appearance: "light" | "dark";
     accentHex: string;
     active: boolean;
 }): import("react/jsx-runtime").JSX.Element;
-export declare function SnapViewCore({ snap, handlers, loading, appearance, loadingOverlay, }: {
+export declare function SnapViewCore({ snap, handlers, loading, appearance, loadingOverlay, initialRenderState, onRenderStateChange, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -19,4 +16,6 @@ export declare function SnapViewCore({ snap, handlers, loading, appearance, load
      * the built-in spinner + backdrop is used. Pass `null` to render nothing.
      */
     loadingOverlay?: ReactNode;
+    initialRenderState?: SnapRenderState;
+    onRenderStateChange?: (state: SnapRenderState) => void;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/react/snap-view-core.js

@@ -6,41 +6,8 @@ import { SnapPreviewAccentProvider } from "./accent-context.js";
 import { SnapVersionProvider } from "./snap-version-context.js";
 import { resolveSnapPaletteHex } from "./lib/resolve-palette-hex.js";
 import { snapPreviewPrimaryCssProperties } from "./lib/preview-primary-css.js";
+import { applyStatePaths, buildInitialRenderState, cloneSnapRenderState, getUnpresentedSnapEffects, markSnapEffectsPresented, } from "../render-state.js";
 import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
-// ─── Internal helpers ──────────────────────────────────
-export function applyStatePaths(model, changes) {
-    if (!changes)
-        return;
-    const entries = Array.isArray(changes)
-        ? changes.map((c) => [c.path, c.value])
-        : 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;
-            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;
-            if (rest.length === 1) {
-                theme[rest[0]] = value;
-            }
-        }
-    }
-}
 function withDefaultElementProps(spec) {
     if (!spec || typeof spec !== "object" || !("elements" in spec))
         return spec;
@@ -102,7 +69,7 @@ function ConfettiOverlay() {
             overflow: "hidden",
             pointerEvents: "none",
             zIndex: 20,
-        }, children: [pieces.map(({ id, left, delay, duration, color, size, rotation, isCircle, driftX, driftMid }) => (_jsx("div", { style: {
+        }, children: [pieces.map(({ id, left, delay, duration, color, size, rotation, isCircle, driftX, driftMid, }) => (_jsx("div", { style: {
                     position: "absolute",
                     left: `${left}%`,
                     top: -20,
@@ -199,9 +166,7 @@ export function SnapLoadingOverlay({ appearance, accentHex, active, }) {
             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",
@@ -239,19 +204,16 @@ const PALETTE = [
 ];
 // ─── SnapViewCore ────────────────────────────────────
 // Shared rendering logic used by both v1 and v2.
-export function SnapViewCore({ snap, handlers, loading = false, appearance = "dark", loadingOverlay, }) {
+export function SnapViewCore({ snap, handlers, loading = false, appearance = "dark", loadingOverlay, initialRenderState, onRenderStateChange, }) {
     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(initialState);
     useEffect(() => {
-        stateRef.current = {
-            inputs: {
-                ...(initialState.inputs ?? {}),
-            },
-            theme: {
-                ...(initialState.theme ?? {}),
-            },
-        };
+        stateRef.current = cloneSnapRenderState(initialState);
     }, [initialState]);
     useEffect(() => {
         const catalogResult = snapJsonRenderCatalog.validate(spec);
@@ -264,16 +226,49 @@ export function SnapViewCore({ snap, handlers, loading = false, appearance = "da
     useEffect(() => {
         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";
     const accentHex = useMemo(() => resolveSnapPaletteHex(accentName, appearance), [accentName, appearance]);
     const previewSurfaceStyle = useMemo(() => {
@@ -339,7 +334,8 @@ export function SnapViewCore({ snap, handlers, loading = false, appearance = "da
                 break;
         }
     }, [handlers]);
-    return (_jsxs("div", { style: { position: "relative", width: "100%" }, children: [showConfetti && _jsx(ConfettiOverlay, {}, confettiKey), showFireworks && _jsx(FireworksOverlay, {}, fireworksKey), loadingOverlay === undefined ? (_jsx(SnapLoadingOverlay, { appearance: appearance, accentHex: accentHex, active: loading })) : loading ? (_jsx(_Fragment, { children: loadingOverlay })) : null, _jsx("div", { style: previewSurfaceStyle, children: _jsx(SnapPreviewAccentProvider, { pageAccent: snap.theme?.accent, appearance: appearance, children: _jsx(SnapVersionProvider, { value: snap.version === "2.0" ? "2.0" : "1.0", children: _jsx(SnapCatalogView, { spec: spec, state: initialState, loading: false, onStateChange: (changes) => {
+    return (_jsxs("div", { style: { position: "relative", width: "100%" }, children: [showConfetti && effectRunKeys.confetti > 0 && (_jsx(ConfettiOverlay, {}, effectRunKeys.confetti)), showFireworks && effectRunKeys.fireworks > 0 && (_jsx(FireworksOverlay, {}, effectRunKeys.fireworks)), loadingOverlay === undefined ? (_jsx(SnapLoadingOverlay, { appearance: appearance, accentHex: accentHex, active: loading })) : loading ? (_jsx(_Fragment, { children: loadingOverlay })) : null, _jsx("div", { style: previewSurfaceStyle, children: _jsx(SnapPreviewAccentProvider, { pageAccent: snap.theme?.accent, appearance: appearance, children: _jsx(SnapVersionProvider, { value: snap.version === "2.0" ? "2.0" : "1.0", children: _jsx(SnapCatalogView, { spec: spec, state: initialState, loading: false, onStateChange: (changes) => {
                                 applyStatePaths(stateRef.current, changes);
+                                onRenderStateChange?.(cloneSnapRenderState(stateRef.current));
                             }, onAction: handleAction }, pageKey) }) }) })] }));
 }

package/dist/react/v1/snap-view.d.ts

@@ -1,14 +1,16 @@
 import { type ReactNode } from "react";
-import type { SnapPage, SnapActionHandlers } from "../index.js";
-export declare function SnapViewV1({ snap, handlers, loading, appearance, loadingOverlay, }: {
+import type { SnapActionHandlers, SnapPage, SnapRenderState } from "../index.js";
+export declare function SnapViewV1({ snap, handlers, loading, appearance, loadingOverlay, initialRenderState, onRenderStateChange, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
     appearance?: "light" | "dark";
     /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
     loadingOverlay?: ReactNode;
+    initialRenderState?: SnapRenderState;
+    onRenderStateChange?: (state: SnapRenderState) => void;
 }): import("react/jsx-runtime").JSX.Element;
-export declare function SnapCardV1({ snap, handlers, loading, appearance, maxWidth, actionError, plain, loadingOverlay, }: {
+export declare function SnapCardV1({ snap, handlers, loading, appearance, maxWidth, actionError, plain, loadingOverlay, initialRenderState, onRenderStateChange, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -18,4 +20,8 @@ export declare function SnapCardV1({ snap, handlers, loading, appearance, maxWid
     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;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/react/v1/snap-view.js

@@ -4,10 +4,10 @@ import { useEffect, useMemo, useRef, useState } from "react";
 import { SnapViewCore, SnapLoadingOverlay } from "../snap-view-core.js";
 import { resolveSnapPaletteHex } from "../lib/resolve-palette-hex.js";
 const SNAP_MAX_HEIGHT = 500;
-export function SnapViewV1({ snap, handlers, loading = false, appearance = "dark", loadingOverlay, }) {
-    return (_jsx(SnapViewCore, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, loadingOverlay: loadingOverlay }));
+export function SnapViewV1({ snap, handlers, loading = false, appearance = "dark", loadingOverlay, initialRenderState, onRenderStateChange, }) {
+    return (_jsx(SnapViewCore, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, loadingOverlay: loadingOverlay, initialRenderState: initialRenderState, onRenderStateChange: onRenderStateChange }));
 }
-export function SnapCardV1({ snap, handlers, loading = false, appearance = "dark", maxWidth = 480, actionError, plain = false, loadingOverlay, }) {
+export function SnapCardV1({ snap, handlers, loading = false, appearance = "dark", maxWidth = 480, actionError, plain = false, loadingOverlay, initialRenderState, onRenderStateChange, }) {
     const isDark = appearance === "dark";
     const borderColor = isDark ? "rgba(255,255,255,0.1)" : "rgba(0,0,0,0.1)";
     const surfaceBg = isDark ? "rgba(255,255,255,0.05)" : "rgba(0,0,0,0.02)";
@@ -62,7 +62,7 @@ export function SnapCardV1({ snap, handlers, loading = false, appearance = "dark
                                 maxHeight: SNAP_MAX_HEIGHT,
                                 overflow: "hidden",
                             }
-                            : undefined, children: _jsx("div", { ref: contentRef, style: plain ? undefined : { padding: 16 }, children: _jsx(SnapViewV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, loadingOverlay: null }) }) }), loadingOverlay === undefined ? (_jsx(SnapLoadingOverlay, { appearance: appearance, accentHex: accentHex, active: loading })) : loading ? (_jsx(_Fragment, { children: loadingOverlay })) : null] }), isExpandable ? (_jsx("button", { type: "button", "aria-expanded": isExpanded, onClick: () => setIsExpanded((value) => !value), style: {
+                            : undefined, children: _jsx("div", { ref: contentRef, style: plain ? undefined : { padding: 16 }, children: _jsx(SnapViewV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, loadingOverlay: null, initialRenderState: initialRenderState, onRenderStateChange: onRenderStateChange }) }) }), loadingOverlay === undefined ? (_jsx(SnapLoadingOverlay, { appearance: appearance, accentHex: accentHex, active: loading })) : loading ? (_jsx(_Fragment, { children: loadingOverlay })) : null] }), isExpandable ? (_jsx("button", { type: "button", "aria-expanded": isExpanded, onClick: () => setIsExpanded((value) => !value), style: {
                     position: "absolute",
                     bottom: 0,
                     left: "50%",

package/dist/react/v2/snap-view.d.ts

@@ -1,7 +1,7 @@
 import { type ReactNode } from "react";
 import type { ValidationResult } from "../../validator.js";
-import type { SnapPage, SnapActionHandlers } from "../index.js";
-export declare function SnapViewV2({ snap, handlers, loading, appearance, onValidationError, validationErrorFallback, loadingOverlay, }: {
+import type { SnapActionHandlers, SnapPage, SnapRenderState } from "../index.js";
+export declare function SnapViewV2({ snap, handlers, loading, appearance, onValidationError, validationErrorFallback, loadingOverlay, initialRenderState, onRenderStateChange, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -10,8 +10,10 @@ export declare function SnapViewV2({ snap, handlers, loading, appearance, onVali
     validationErrorFallback?: ReactNode;
     /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
     loadingOverlay?: ReactNode;
+    initialRenderState?: SnapRenderState;
+    onRenderStateChange?: (state: SnapRenderState) => void;
 }): import("react/jsx-runtime").JSX.Element | null;
-export declare function SnapCardV2({ snap, handlers, loading, appearance, maxWidth, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, loadingOverlay, }: {
+export declare function SnapCardV2({ snap, handlers, loading, appearance, maxWidth, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, loadingOverlay, initialRenderState, onRenderStateChange, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -24,4 +26,8 @@ export declare function SnapCardV2({ snap, handlers, loading, appearance, maxWid
     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;
 }): import("react/jsx-runtime").JSX.Element;

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

@@ -21,7 +21,7 @@ function SnapValidationFallback({ appearance, message, }) {
         }, children: _jsx("span", { children: message ? `Unable to render snap: ${message}` : "Unable to render snap" }) }));
 }
 // ─── SnapViewV2 ──────────────────────────────────────
-export function SnapViewV2({ snap, handlers, loading = false, appearance = "dark", onValidationError, validationErrorFallback, loadingOverlay, }) {
+export function SnapViewV2({ snap, handlers, loading = false, appearance = "dark", onValidationError, validationErrorFallback, loadingOverlay, initialRenderState, onRenderStateChange, }) {
     const validation = useMemo(() => validateSnapResponse(snap), [snap]);
     const valid = validation.valid;
     const validationMessage = validation.issues[0]?.message;
@@ -41,10 +41,10 @@ export function SnapViewV2({ snap, handlers, loading = false, appearance = "dark
             return null;
         return _jsx(_Fragment, { children: validationErrorFallback ?? _jsx(SnapValidationFallback, { appearance: appearance, message: validationMessage }) });
     }
-    return (_jsx(SnapViewCore, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, loadingOverlay: loadingOverlay }));
+    return (_jsx(SnapViewCore, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, loadingOverlay: loadingOverlay, initialRenderState: initialRenderState, onRenderStateChange: onRenderStateChange }));
 }
 // ─── SnapCardV2 ──────────────────────────────────────
-export function SnapCardV2({ snap, handlers, loading = false, appearance = "dark", maxWidth = 480, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, loadingOverlay, }) {
+export function SnapCardV2({ snap, handlers, loading = false, appearance = "dark", maxWidth = 480, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, loadingOverlay, initialRenderState, onRenderStateChange, }) {
     const isDark = appearance === "dark";
     const bg = isDark ? "rgba(0,0,0,0.85)" : "rgba(255,255,255,0.9)";
     const borderColor = isDark ? "rgba(255,255,255,0.1)" : "rgba(0,0,0,0.1)";
@@ -101,7 +101,7 @@ export function SnapCardV2({ snap, handlers, loading = false, appearance = "dark
                             }),
                         }, children: [_jsx("div", { style: isClipped
                                     ? { maxHeight: SNAP_MAX_HEIGHT, overflow: "hidden" }
-                                    : undefined, children: _jsx("div", { ref: contentRef, style: plain ? undefined : { padding: 16 }, children: _jsx(SnapViewV2, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, loadingOverlay: null }) }) }), loadingOverlay === undefined ? (_jsx(SnapLoadingOverlay, { appearance: appearance, accentHex: accentHex, active: loading })) : loading ? (_jsx(_Fragment, { children: loadingOverlay })) : null, showOverflowWarning && (_jsxs("div", { style: {
+                                    : undefined, children: _jsx("div", { ref: contentRef, style: plain ? undefined : { padding: 16 }, children: _jsx(SnapViewV2, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, loadingOverlay: null, initialRenderState: initialRenderState, onRenderStateChange: onRenderStateChange }) }) }), loadingOverlay === undefined ? (_jsx(SnapLoadingOverlay, { appearance: appearance, accentHex: accentHex, active: loading })) : loading ? (_jsx(_Fragment, { children: loadingOverlay })) : null, showOverflowWarning && (_jsxs("div", { style: {
                                     position: "absolute",
                                     top: SNAP_MAX_HEIGHT,
                                     left: 0,

package/dist/react-native/index.d.ts

@@ -1,13 +1,13 @@
 import type { ReactNode } from "react";
 import type { ValidationResult } from "@farcaster/snap";
 import type { SnapNativeColors } from "./theme.js";
-import type { SnapPage, SnapActionHandlers } from "./types.js";
+import type { SnapActionHandlers, SnapPage, SnapRenderState } from "./types.js";
 import { useSnapTheme } from "./theme.js";
 import { hexToRgba } from "./use-snap-palette.js";
-export type { JsonValue, SnapPage, SnapActionHandlers } from "./types.js";
+export type { JsonValue, SnapActionHandlers, SnapPage, SnapRenderState, } from "./types.js";
 export { useSnapTheme, hexToRgba };
 export type { SnapNativeColors };
-export declare function SnapCard({ snap, handlers, loading, appearance, colors, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, }: {
+export declare function SnapCard({ snap, handlers, loading, appearance, colors, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, initialRenderState, onRenderStateChange, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -33,4 +33,8 @@ export declare function SnapCard({ snap, handlers, loading, appearance, colors,
     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;
 }): import("react").JSX.Element;

package/dist/react-native/index.js

@@ -7,9 +7,9 @@ import { SnapCardV2 } from "./v2/snap-view.js";
 // ─── Re-exports ───────────────────────────────────────
 export { useSnapTheme, hexToRgba };
 // ─── SnapCard (version-switching) ─────────────────────
-export function SnapCard({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, }) {
+export function SnapCard({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, initialRenderState, onRenderStateChange, }) {
     if (snap.version === SPEC_VERSION_2) {
-        return (_jsx(SnapCardV2, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, colors: colors, borderRadius: borderRadius, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, plain: plain, loadingOverlay: loadingOverlay, forceExpanded: forceExpanded, expandButtonLabel: expandButtonLabel, onExpandPress: onExpandPress }));
+        return (_jsx(SnapCardV2, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, colors: colors, borderRadius: borderRadius, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, plain: plain, loadingOverlay: loadingOverlay, forceExpanded: forceExpanded, expandButtonLabel: expandButtonLabel, onExpandPress: onExpandPress, initialRenderState: initialRenderState, onRenderStateChange: onRenderStateChange }));
     }
-    return (_jsx(SnapCardV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, colors: colors, borderRadius: borderRadius, actionError: actionError, plain: plain, loadingOverlay: loadingOverlay, forceExpanded: forceExpanded, expandButtonLabel: expandButtonLabel, onExpandPress: onExpandPress }));
+    return (_jsx(SnapCardV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, colors: colors, borderRadius: borderRadius, actionError: actionError, plain: plain, loadingOverlay: loadingOverlay, forceExpanded: forceExpanded, expandButtonLabel: expandButtonLabel, onExpandPress: onExpandPress, initialRenderState: initialRenderState, onRenderStateChange: onRenderStateChange }));
 }

package/dist/react-native/snap-view-core.d.ts

@@ -1,11 +1,8 @@
 import { type ReactNode } from "react";
+import { type SnapRenderState } from "../render-state.js";
 import type { SnapPage, SnapActionHandlers } from "./types.js";
-export declare function applyStatePaths(model: Record<string, unknown>, changes: {
-    path: string;
-    value: unknown;
-}[] | Record<string, unknown> | null | undefined): void;
 export declare function resolveAccentHex(accent: string | undefined, appearance: "light" | "dark"): string;
-export declare function SnapViewCoreInner({ snap, handlers, loading, loadingOverlay, }: {
+export declare function SnapViewCoreInner({ snap, handlers, loading, loadingOverlay, initialRenderState, onRenderStateChange, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -14,6 +11,8 @@ export declare function SnapViewCoreInner({ snap, handlers, loading, loadingOver
      * the built-in ActivityIndicator overlay is used. Pass `null` to render nothing.
      */
     loadingOverlay?: ReactNode;
+    initialRenderState?: SnapRenderState;
+    onRenderStateChange?: (state: SnapRenderState) => void;
 }): import("react").JSX.Element;
 export declare function SnapLoadingOverlay({ appearance, accentHex, }: {
     appearance: "light" | "dark";

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

@@ -8,40 +8,7 @@ import { SnapVersionProvider } from "./snap-version-context.js";
 import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
 import { ActivityIndicator, StyleSheet, View } from "react-native";
 import { DEFAULT_THEME_ACCENT, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, } from "@farcaster/snap";
-// ─── Shared helpers ──────────────────────────────────
-export function applyStatePaths(model, changes) {
-    if (!changes)
-        return;
-    const entries = Array.isArray(changes)
-        ? changes.map((c) => [c.path, c.value])
-        : 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;
-            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;
-            if (rest.length === 1) {
-                theme[rest[0]] = value;
-            }
-        }
-    }
-}
+import { applyStatePaths, buildInitialRenderState, cloneSnapRenderState, getUnpresentedSnapEffects, markSnapEffectsPresented, } from "../render-state.js";
 function withDefaultElementProps(spec) {
     if (!spec || typeof spec !== "object" || !("elements" in spec))
         return spec;
@@ -70,28 +37,18 @@ export function resolveAccentHex(accent, appearance) {
     return map[name];
 }
 // ─── Core rendering component (no validation) ────────
-export function SnapViewCoreInner({ snap, handlers, loading = false, loadingOverlay, }) {
+export function SnapViewCoreInner({ snap, handlers, loading = false, loadingOverlay, initialRenderState, onRenderStateChange, }) {
     const { mode } = useSnapTheme();
     const spec = useMemo(() => withDefaultElementProps(snap.ui), [snap.ui]);
     const accentHex = resolveAccentHex(snap.theme?.accent, mode);
-    const initialState = useMemo(() => ({
-        ...(spec.state ?? {}),
-        inputs: { ...(spec.state?.inputs ?? {}) },
-        theme: {
-            ...(spec.state?.theme ?? {}),
-            ...(snap.theme ? { accent: snap.theme.accent } : {}),
-        },
-    }), [spec, snap.theme]);
+    const initialState = useMemo(() => buildInitialRenderState({
+        specState: spec.state,
+        initialRenderState,
+        themeAccent: snap.theme?.accent,
+    }), [initialRenderState, spec.state, snap.theme?.accent]);
     const stateRef = useRef(initialState);
     useEffect(() => {
-        stateRef.current = {
-            inputs: {
-                ...(initialState.inputs ?? {}),
-            },
-            theme: {
-                ...(initialState.theme ?? {}),
-            },
-        };
+        stateRef.current = cloneSnapRenderState(initialState);
     }, [initialState]);
     useEffect(() => {
         const catalogResult = snapJsonRenderCatalog.validate(spec);
@@ -104,16 +61,49 @@ export function SnapViewCoreInner({ snap, handlers, loading = false, loadingOver
     useEffect(() => {
         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;
     const handleAction = useCallback((name, params) => {
@@ -169,21 +159,16 @@ export function SnapViewCoreInner({ snap, handlers, loading = false, loadingOver
                 break;
         }
     }, []);
-    return (_jsxs(View, { style: styles.container, children: [loading
-                ? loadingOverlay === undefined
-                    ? (_jsx(SnapLoadingOverlay, { appearance: mode, accentHex: accentHex }))
-                    : loadingOverlay
-                : null, _jsx(SnapVersionProvider, { value: snap.version === "2.0" ? "2.0" : "1.0", children: _jsx(SnapCatalogView, { spec: spec, state: initialState, loading: false, onStateChange: (changes) => {
+    return (_jsxs(View, { style: styles.container, children: [loading ? (loadingOverlay === undefined ? (_jsx(SnapLoadingOverlay, { appearance: mode, accentHex: accentHex })) : (loadingOverlay)) : null, _jsx(SnapVersionProvider, { value: snap.version === "2.0" ? "2.0" : "1.0", children: _jsx(SnapCatalogView, { spec: spec, state: initialState, loading: false, onStateChange: (changes) => {
                         applyStatePaths(stateRef.current, changes);
-                    }, onAction: handleAction }, pageKey) }), showConfetti && _jsx(ConfettiOverlay, {}, confettiKey), showFireworks && _jsx(FireworksOverlay, {}, fireworksKey)] }));
+                        onRenderStateChange?.(cloneSnapRenderState(stateRef.current));
+                    }, onAction: handleAction }, pageKey) }), showConfetti && effectRunKeys.confetti > 0 && (_jsx(ConfettiOverlay, {}, effectRunKeys.confetti)), showFireworks && effectRunKeys.fireworks > 0 && (_jsx(FireworksOverlay, {}, effectRunKeys.fireworks))] }));
 }
 export function SnapLoadingOverlay({ appearance, accentHex, }) {
     return (_jsx(View, { style: [
             styles.overlay,
             {
-                backgroundColor: appearance === "dark"
-                    ? "rgba(0,0,0,0.1)"
-                    : "rgba(255,255,255,0.2)",
+                backgroundColor: appearance === "dark" ? "rgba(0,0,0,0.1)" : "rgba(255,255,255,0.2)",
             },
         ], children: _jsx(ActivityIndicator, { size: "large", color: accentHex }) }));
 }

package/dist/react-native/types.d.ts

@@ -1,4 +1,6 @@
 import type { Spec } from "@json-render/core";
+import type { SnapRenderState } from "../render-state.js";
+export type { SnapRenderState };
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };

package/dist/react-native/v1/snap-view.d.ts

@@ -1,13 +1,15 @@
 import { type ReactNode } from "react";
 import { type SnapNativeColors } from "../theme.js";
-import type { SnapPage, SnapActionHandlers } from "../types.js";
-export declare function SnapViewV1Inner({ snap, handlers, loading, loadingOverlay, }: {
+import type { SnapActionHandlers, SnapPage, SnapRenderState } from "../types.js";
+export declare function SnapViewV1Inner({ snap, handlers, loading, loadingOverlay, initialRenderState, onRenderStateChange, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
     loadingOverlay?: ReactNode;
+    initialRenderState?: SnapRenderState;
+    onRenderStateChange?: (state: SnapRenderState) => void;
 }): import("react").JSX.Element;
-export declare function SnapViewV1({ snap, handlers, loading, appearance, colors, loadingOverlay, }: {
+export declare function SnapViewV1({ snap, handlers, loading, appearance, colors, loadingOverlay, initialRenderState, onRenderStateChange, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -15,8 +17,10 @@ export declare function SnapViewV1({ snap, handlers, loading, appearance, colors
     colors?: Partial<SnapNativeColors>;
     /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
     loadingOverlay?: ReactNode;
+    initialRenderState?: SnapRenderState;
+    onRenderStateChange?: (state: SnapRenderState) => void;
 }): import("react").JSX.Element;
-export declare function SnapCardV1({ snap, handlers, loading, appearance, colors, borderRadius, actionError, plain, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, }: {
+export declare function SnapCardV1({ snap, handlers, loading, appearance, colors, borderRadius, actionError, plain, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, initialRenderState, onRenderStateChange, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -33,4 +37,8 @@ export declare function SnapCardV1({ snap, handlers, loading, appearance, colors
     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;
 }): import("react").JSX.Element;