@farcaster/snap 2.6.4 → 2.7.0

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

@@ -5,14 +5,14 @@ import { SnapThemeProvider, useSnapTheme } from "../theme.js";
 import { SnapLoadingOverlay, SnapViewCoreInner, resolveAccentHex, } from "../snap-view-core.js";
 import { getSnapExpansionState } from "../expand-state.js";
 // ─── SnapViewV1 (no validation) ──────────────────────
-export function SnapViewV1Inner({ snap, handlers, loading = false, loadingOverlay, }) {
-    return (_jsx(SnapViewCoreInner, { snap: snap, handlers: handlers, loading: loading, loadingOverlay: loadingOverlay }));
+export function SnapViewV1Inner({ snap, handlers, loading = false, loadingOverlay, initialRenderState, onRenderStateChange, }) {
+    return (_jsx(SnapViewCoreInner, { snap: snap, handlers: handlers, loading: loading, loadingOverlay: loadingOverlay, initialRenderState: initialRenderState, onRenderStateChange: onRenderStateChange }));
 }
-export function SnapViewV1({ snap, handlers, loading = false, appearance = "dark", colors, loadingOverlay, }) {
-    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapViewV1Inner, { snap: snap, handlers: handlers, loading: loading, loadingOverlay: loadingOverlay }) }));
+export function SnapViewV1({ snap, handlers, loading = false, appearance = "dark", colors, loadingOverlay, initialRenderState, onRenderStateChange, }) {
+    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapViewV1Inner, { snap: snap, handlers: handlers, loading: loading, loadingOverlay: loadingOverlay, initialRenderState: initialRenderState, onRenderStateChange: onRenderStateChange }) }));
 }
 // ─── SnapCardV1 (card frame with expandable clipping) ──
-function SnapCardV1Inner({ snap, handlers, loading = false, borderRadius, actionError, appearance, plain, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, }) {
+function SnapCardV1Inner({ snap, handlers, loading = false, borderRadius, actionError, appearance, plain, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, initialRenderState, onRenderStateChange, }) {
     const { colors, mode } = useSnapTheme();
     const accentHex = resolveAccentHex(snap.theme?.accent, mode);
     const [contentHeight, setContentHeight] = useState(0);
@@ -48,7 +48,7 @@ function SnapCardV1Inner({ snap, handlers, loading = false, borderRadius, action
                                             : currentHeight === nextHeight
                                                 ? currentHeight
                                                 : nextHeight);
-                                    }, style: plain ? undefined : cardStyles.body, children: _jsx(SnapViewV1Inner, { snap: snap, handlers: handlers, loading: loading, loadingOverlay: null }) }) }), loading
+                                    }, style: plain ? undefined : cardStyles.body, children: _jsx(SnapViewV1Inner, { snap: snap, handlers: handlers, loading: loading, loadingOverlay: null, initialRenderState: initialRenderState, onRenderStateChange: onRenderStateChange }) }) }), loading
                                 ? loadingOverlay === undefined
                                     ? _jsx(SnapLoadingOverlay, { appearance: mode, accentHex: accentHex })
                                     : loadingOverlay
@@ -76,8 +76,8 @@ function SnapCardV1Inner({ snap, handlers, loading = false, borderRadius, action
                     },
                 ], children: actionError }))] }));
 }
-export function SnapCardV1({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, actionError, plain = false, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, }) {
-    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapCardV1Inner, { snap: snap, handlers: handlers, loading: loading, borderRadius: borderRadius, actionError: actionError, appearance: appearance, plain: plain, loadingOverlay: loadingOverlay, forceExpanded: forceExpanded, expandButtonLabel: expandButtonLabel, onExpandPress: onExpandPress }) }));
+export function SnapCardV1({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, actionError, plain = false, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, initialRenderState, onRenderStateChange, }) {
+    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapCardV1Inner, { snap: snap, handlers: handlers, loading: loading, borderRadius: borderRadius, actionError: actionError, appearance: appearance, plain: plain, loadingOverlay: loadingOverlay, forceExpanded: forceExpanded, expandButtonLabel: expandButtonLabel, onExpandPress: onExpandPress, initialRenderState: initialRenderState, onRenderStateChange: onRenderStateChange }) }));
 }
 const cardStyles = StyleSheet.create({
     frameRing: { alignSelf: "stretch" },

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

@@ -1,16 +1,18 @@
 import type { ReactNode } from "react";
 import { type SnapNativeColors } from "../theme.js";
 import { type ValidationResult } from "@farcaster/snap";
-import type { SnapPage, SnapActionHandlers } from "../types.js";
-export declare function SnapViewV2Inner({ snap, handlers, loading, onValidationError, validationErrorFallback, loadingOverlay, }: {
+import type { SnapActionHandlers, SnapPage, SnapRenderState } from "../types.js";
+export declare function SnapViewV2Inner({ snap, handlers, loading, onValidationError, validationErrorFallback, loadingOverlay, initialRenderState, onRenderStateChange, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
     onValidationError?: (result: ValidationResult) => void;
     validationErrorFallback?: ReactNode;
     loadingOverlay?: ReactNode;
+    initialRenderState?: SnapRenderState;
+    onRenderStateChange?: (state: SnapRenderState) => void;
 }): import("react").JSX.Element;
-export declare function SnapViewV2({ snap, handlers, loading, appearance, colors, onValidationError, validationErrorFallback, loadingOverlay, }: {
+export declare function SnapViewV2({ snap, handlers, loading, appearance, colors, onValidationError, validationErrorFallback, loadingOverlay, initialRenderState, onRenderStateChange, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -20,8 +22,10 @@ export declare function SnapViewV2({ snap, handlers, loading, appearance, colors
     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.Element;
-export declare function SnapCardV2({ snap, handlers, loading, appearance, colors, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, }: {
+export declare function SnapCardV2({ snap, handlers, loading, appearance, colors, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, plain, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, initialRenderState, onRenderStateChange, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
@@ -41,4 +45,8 @@ export declare function SnapCardV2({ 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/v2/snap-view.js

@@ -25,7 +25,7 @@ const fallbackStyles = StyleSheet.create({
     },
 });
 // ─── SnapViewV2 (with validation) ────────────────────
-export function SnapViewV2Inner({ snap, handlers, loading = false, onValidationError, validationErrorFallback, loadingOverlay, }) {
+export function SnapViewV2Inner({ snap, handlers, loading = false, onValidationError, validationErrorFallback, loadingOverlay, initialRenderState, onRenderStateChange, }) {
     const validation = useMemo(() => validateSnapResponse(snap), [snap]);
     const valid = validation.valid;
     const validationMessage = validation.issues[0]?.message;
@@ -45,13 +45,13 @@ export function SnapViewV2Inner({ snap, handlers, loading = false, onValidationE
             return null;
         return (_jsx(_Fragment, { children: validationErrorFallback ?? _jsx(SnapValidationFallback, { message: validationMessage }) }));
     }
-    return (_jsx(SnapViewCoreInner, { snap: snap, handlers: handlers, loading: loading, loadingOverlay: loadingOverlay }));
+    return (_jsx(SnapViewCoreInner, { snap: snap, handlers: handlers, loading: loading, loadingOverlay: loadingOverlay, initialRenderState: initialRenderState, onRenderStateChange: onRenderStateChange }));
 }
-export function SnapViewV2({ snap, handlers, loading = false, appearance = "dark", colors, onValidationError, validationErrorFallback, loadingOverlay, }) {
-    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapViewV2Inner, { snap: snap, handlers: handlers, loading: loading, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, loadingOverlay: loadingOverlay }) }));
+export function SnapViewV2({ snap, handlers, loading = false, appearance = "dark", colors, onValidationError, validationErrorFallback, loadingOverlay, initialRenderState, onRenderStateChange, }) {
+    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapViewV2Inner, { snap: snap, handlers: handlers, loading: loading, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, loadingOverlay: loadingOverlay, initialRenderState: initialRenderState, onRenderStateChange: onRenderStateChange }) }));
 }
 // ─── SnapCardV2 (card frame + height limits) ─────────
-function SnapCardV2Inner({ snap, handlers, loading, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, appearance, plain, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, }) {
+function SnapCardV2Inner({ snap, handlers, loading, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, appearance, plain, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, initialRenderState, onRenderStateChange, }) {
     const { colors, mode } = useSnapTheme();
     const accentHex = resolveAccentHex(snap.theme?.accent, mode);
     const [contentHeight, setContentHeight] = useState(0);
@@ -69,7 +69,7 @@ function SnapCardV2Inner({ snap, handlers, loading, borderRadius, showOverflowWa
         showOverflowWarning,
     });
     const expandButtonInsideCard = typeof onExpandPress === "function";
-    const content = (_jsx(SnapViewV2Inner, { snap: snap, handlers: handlers, loading: loading, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, loadingOverlay: null }));
+    const content = (_jsx(SnapViewV2Inner, { snap: snap, handlers: handlers, loading: loading, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, loadingOverlay: null, initialRenderState: initialRenderState, onRenderStateChange: onRenderStateChange }));
     if (plain) {
         return (_jsxs(_Fragment, { children: [_jsx(View, { style: expansion.clipped
                         ? { maxHeight: expansion.maxHeight, overflow: "hidden" }
@@ -151,8 +151,8 @@ function SnapCardV2Inner({ snap, handlers, loading, borderRadius, showOverflowWa
                         : "rgba(200,0,0,0.8)",
                 }, children: actionError }))] }));
 }
-export function SnapCardV2({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, }) {
-    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapCardV2Inner, { snap: snap, handlers: handlers, loading: loading, borderRadius: borderRadius, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, appearance: appearance, plain: plain, loadingOverlay: loadingOverlay, forceExpanded: forceExpanded, expandButtonLabel: expandButtonLabel, onExpandPress: onExpandPress }) }));
+export function SnapCardV2({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, initialRenderState, onRenderStateChange, }) {
+    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapCardV2Inner, { snap: snap, handlers: handlers, loading: loading, borderRadius: borderRadius, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, appearance: appearance, plain: plain, loadingOverlay: loadingOverlay, forceExpanded: forceExpanded, expandButtonLabel: expandButtonLabel, onExpandPress: onExpandPress, initialRenderState: initialRenderState, onRenderStateChange: onRenderStateChange }) }));
 }
 const cardStyles = StyleSheet.create({
     frameRing: { alignSelf: "stretch" },

package/dist/render-state.d.ts

@@ -0,0 +1,14 @@
+export type SnapRenderState = Record<string, unknown>;
+export type SnapRenderStateChanges = {
+    path: string;
+    value: unknown;
+}[] | Record<string, unknown> | null | undefined;
+export declare function cloneSnapRenderState<T>(value: T): T;
+export declare function applyStatePaths(model: Record<string, unknown>, changes: SnapRenderStateChanges): void;
+export declare function getUnpresentedSnapEffects(model: SnapRenderState, effects: readonly string[] | undefined): string[];
+export declare function markSnapEffectsPresented(model: SnapRenderState, effects: readonly string[] | undefined): boolean;
+export declare function buildInitialRenderState({ specState, initialRenderState, themeAccent, }: {
+    specState: unknown;
+    initialRenderState?: SnapRenderState;
+    themeAccent?: string;
+}): SnapRenderState;

package/dist/render-state.js

@@ -0,0 +1,116 @@
+const SNAP_RENDER_STATE_META_KEY = "__snapRender";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeEffects(effects) {
+    if (!effects)
+        return [];
+    return Array.from(new Set(effects.filter((effect) => typeof effect === "string" && effect.length > 0)));
+}
+function getRenderStateMeta(model) {
+    const meta = model[SNAP_RENDER_STATE_META_KEY];
+    return isRecord(meta) ? meta : undefined;
+}
+function getPresentedSnapEffects(model) {
+    const presentedEffects = getRenderStateMeta(model)?.presentedEffects;
+    if (!Array.isArray(presentedEffects))
+        return new Set();
+    return new Set(presentedEffects.filter((effect) => typeof effect === "string" && effect.length > 0));
+}
+export function cloneSnapRenderState(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => cloneSnapRenderState(item));
+    }
+    if (isRecord(value)) {
+        const next = {};
+        for (const [key, nestedValue] of Object.entries(value)) {
+            next[key] = cloneSnapRenderState(nestedValue);
+        }
+        return next;
+    }
+    return value;
+}
+function mergeRenderState(base, override) {
+    if (!override)
+        return cloneSnapRenderState(base);
+    const next = cloneSnapRenderState(base);
+    for (const [key, value] of Object.entries(override)) {
+        const existing = next[key];
+        next[key] =
+            isRecord(existing) && isRecord(value)
+                ? mergeRenderState(existing, value)
+                : cloneSnapRenderState(value);
+    }
+    return next;
+}
+function normalizeStatePath(path) {
+    const trimmed = path.startsWith("/") ? path.slice(1) : path;
+    return trimmed.split("/").filter(Boolean);
+}
+function setStateValue(model, parts, value) {
+    let cursor = model;
+    for (let index = 0; index < parts.length; index += 1) {
+        const part = parts[index];
+        if (index === parts.length - 1) {
+            cursor[part] = cloneSnapRenderState(value);
+            return;
+        }
+        const next = cursor[part];
+        if (!isRecord(next)) {
+            cursor[part] = {};
+        }
+        cursor = cursor[part];
+    }
+}
+export function applyStatePaths(model, changes) {
+    if (!changes)
+        return;
+    const entries = Array.isArray(changes)
+        ? changes.map((change) => [change.path, change.value])
+        : Object.entries(changes);
+    for (const [path, value] of entries) {
+        const parts = normalizeStatePath(path);
+        if (parts.length === 0)
+            continue;
+        setStateValue(model, parts, value);
+    }
+}
+export function getUnpresentedSnapEffects(model, effects) {
+    const presentedEffects = getPresentedSnapEffects(model);
+    return normalizeEffects(effects).filter((effect) => !presentedEffects.has(effect));
+}
+export function markSnapEffectsPresented(model, effects) {
+    const nextEffects = normalizeEffects(effects);
+    if (nextEffects.length === 0)
+        return false;
+    const presentedEffects = getPresentedSnapEffects(model);
+    let changed = false;
+    for (const effect of nextEffects) {
+        if (!presentedEffects.has(effect)) {
+            presentedEffects.add(effect);
+            changed = true;
+        }
+    }
+    if (!changed)
+        return false;
+    let meta = getRenderStateMeta(model);
+    if (!meta) {
+        meta = {};
+        model[SNAP_RENDER_STATE_META_KEY] = meta;
+    }
+    meta.presentedEffects = Array.from(presentedEffects);
+    return true;
+}
+export function buildInitialRenderState({ specState, initialRenderState, themeAccent, }) {
+    const authoredState = isRecord(specState) ? specState : {};
+    const restoredState = initialRenderState
+        ? mergeRenderState(authoredState, initialRenderState)
+        : cloneSnapRenderState(authoredState);
+    if (!isRecord(restoredState.inputs)) {
+        restoredState.inputs = {};
+    }
+    const theme = isRecord(restoredState.theme) ? restoredState.theme : {};
+    restoredState.theme =
+        themeAccent === undefined ? theme : { ...theme, accent: themeAccent };
+    return restoredState;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farcaster/snap",
-  "version": "2.6.4",
+  "version": "2.7.0",
   "description": "Farcaster Snaps 🫰",
   "repository": {
     "type": "git",

package/src/index.ts

@@ -47,3 +47,4 @@ export {
   type SnapGetPayload,
 } from "./schemas";
 export { validateSnapResponse, type ValidationResult } from "./validator";
+export type { SnapRenderState } from "./render-state";

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";
 
@@ -46,6 +47,8 @@ export type SnapActionHandlers = {
   swap_token: (params: { sellToken?: string; buyToken?: string }) => void;
 };
 
+export type { SnapRenderState };
+
 // ─── SnapCard ────────────────────────────────────────
 
 export function SnapCard({
@@ -60,6 +63,8 @@ export function SnapCard({
   actionError,
   plain = false,
   loadingOverlay,
+  initialRenderState,
+  onRenderStateChange,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -76,6 +81,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 +100,8 @@ export function SnapCard({
         actionError={actionError}
         plain={plain}
         loadingOverlay={loadingOverlay}
+        initialRenderState={initialRenderState}
+        onRenderStateChange={onRenderStateChange}
       />
     );
   }
@@ -105,6 +116,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,47 +26,6 @@ import {
 } 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>
-    | 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<
@@ -137,7 +104,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 +157,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 +265,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 +324,8 @@ export function SnapViewCore({
   loading = false,
   appearance = "dark",
   loadingOverlay,
+  initialRenderState,
+  onRenderStateChange,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -359,21 +336,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 +369,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(() => {
-    if (showConfetti) setConfettiKey((k) => k + 1);
-    if (showFireworks) setFireworksKey((k) => k + 1);
-  }, [showConfetti, showFireworks, snap]);
+    onRenderStateChangeRef.current = onRenderStateChange;
+  }, [onRenderStateChange]);
+  useEffect(() => {
+    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";
 
@@ -478,8 +502,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 +531,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>