@farcaster/snap 1.15.4 → 1.16.0

package/dist/constants.d.ts

@@ -1,4 +1,8 @@
+export declare const SPEC_VERSION_1: "1.0";
+export declare const SPEC_VERSION_2: "2.0";
 export declare const SPEC_VERSION: "1.0";
+export declare const SUPPORTED_SPEC_VERSIONS: readonly ["1.0", "2.0"];
+export type SpecVersion = (typeof SUPPORTED_SPEC_VERSIONS)[number];
 export declare const MEDIA_TYPE: "application/vnd.farcaster.snap+json";
 export declare const EFFECT_VALUES: readonly ["confetti"];
 export declare const POST_GRID_TAP_KEY: "grid_tap";
@@ -7,5 +11,9 @@ export declare const GRID_MAX_COLS = 32;
 export declare const GRID_MIN_ROWS = 2;
 export declare const GRID_MAX_ROWS = 16;
 export declare const GRID_GAP_VALUES: readonly ["none", "sm", "md", "lg"];
+export declare const MAX_ELEMENTS = 64;
+export declare const MAX_ROOT_CHILDREN = 7;
+export declare const MAX_CHILDREN = 6;
+export declare const MAX_DEPTH = 4;
 export declare const BAR_CHART_MAX_BARS = 6;
 export declare const BAR_CHART_LABEL_MAX_CHARS = 40;

package/dist/constants.js

@@ -1,4 +1,7 @@
-export const SPEC_VERSION = "1.0";
+export const SPEC_VERSION_1 = "1.0";
+export const SPEC_VERSION_2 = "2.0";
+export const SPEC_VERSION = SPEC_VERSION_1;
+export const SUPPORTED_SPEC_VERSIONS = [SPEC_VERSION_1, SPEC_VERSION_2];
 export const MEDIA_TYPE = "application/vnd.farcaster.snap+json";
 export const EFFECT_VALUES = ["confetti"];
 // ─── Pixel grid ────────────────────────────────────────
@@ -8,6 +11,11 @@ export const GRID_MAX_COLS = 32;
 export const GRID_MIN_ROWS = 2;
 export const GRID_MAX_ROWS = 16;
 export const GRID_GAP_VALUES = ["none", "sm", "md", "lg"];
+// ─── Snap structural limits ───────────────────────────
+export const MAX_ELEMENTS = 64;
+export const MAX_ROOT_CHILDREN = 7;
+export const MAX_CHILDREN = 6;
+export const MAX_DEPTH = 4;
 // ─── Bar chart ─────────────────────────────────────────
 export const BAR_CHART_MAX_BARS = 6;
 export const BAR_CHART_LABEL_MAX_CHARS = 40;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export type { Spec as SnapSpec, UIElement as SnapUIElement, } from "@json-render/core";
-export { SPEC_VERSION, MEDIA_TYPE, EFFECT_VALUES, POST_GRID_TAP_KEY, } from "./constants.js";
+export { SPEC_VERSION, SPEC_VERSION_1, SPEC_VERSION_2, SUPPORTED_SPEC_VERSIONS, type SpecVersion, MEDIA_TYPE, EFFECT_VALUES, POST_GRID_TAP_KEY, MAX_ELEMENTS, MAX_ROOT_CHILDREN, MAX_CHILDREN, MAX_DEPTH, } from "./constants.js";
 export { DEFAULT_THEME_ACCENT, PALETTE_COLOR, PALETTE_COLOR_ACCENT, PALETTE_COLOR_VALUES, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, type PaletteColor, } from "./colors.js";
 export { ACTION_TYPE_GET, ACTION_TYPE_POST, snapResponseSchema, payloadSchema, type SnapAction, type SnapContext, type SnapResponse, type SnapHandlerResult, type SnapElementInput, type SnapSpecInput, type SnapFunction, type SnapPayload, } from "./schemas.js";
 export { validateSnapResponse, type ValidationResult } from "./validator.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { SPEC_VERSION, MEDIA_TYPE, EFFECT_VALUES, POST_GRID_TAP_KEY, } from "./constants.js";
+export { SPEC_VERSION, SPEC_VERSION_1, SPEC_VERSION_2, SUPPORTED_SPEC_VERSIONS, MEDIA_TYPE, EFFECT_VALUES, POST_GRID_TAP_KEY, MAX_ELEMENTS, MAX_ROOT_CHILDREN, MAX_CHILDREN, MAX_DEPTH, } from "./constants.js";
 export { DEFAULT_THEME_ACCENT, PALETTE_COLOR, PALETTE_COLOR_ACCENT, PALETTE_COLOR_VALUES, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, } from "./colors.js";
 export { ACTION_TYPE_GET, ACTION_TYPE_POST, snapResponseSchema, payloadSchema, } from "./schemas.js";
 export { validateSnapResponse } from "./validator.js";

package/dist/react/components/badge.js

@@ -1,7 +1,7 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Badge } from "@neynar/ui/badge";
-import { useSnapColors, pickForegroundForBg } from "../hooks/use-snap-colors.js";
+import { useSnapColors } from "../hooks/use-snap-colors.js";
 import { ICON_MAP } from "./icon.js";
 export function SnapBadge({ element: { props }, }) {
     const content = String(props.label ?? "");
@@ -10,10 +10,9 @@ export function SnapBadge({ element: { props }, }) {
     const iconName = props.icon ? String(props.icon) : undefined;
     const colors = useSnapColors();
     const badgeColor = colors.colorHex(color);
-    const badgeFg = variant === "default" ? pickForegroundForBg(badgeColor) : badgeColor;
     const Icon = iconName ? ICON_MAP[iconName] : undefined;
     const style = variant === "outline"
         ? { borderColor: badgeColor, color: badgeColor, backgroundColor: "transparent" }
-        : { backgroundColor: badgeColor, color: badgeFg, borderColor: "transparent" };
+        : { backgroundColor: `${badgeColor}20`, color: badgeColor, borderColor: "transparent" };
     return (_jsxs(Badge, { variant: variant, className: "gap-1", style: style, children: [Icon && _jsx(Icon, { size: 12 }), content] }));
 }

package/dist/react/index.d.ts

@@ -1,4 +1,6 @@
 import type { Spec } from "@json-render/core";
+import type { ReactNode } from "react";
+import type { ValidationResult } from "../validator.js";
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
@@ -12,9 +14,7 @@ export type SnapPage = {
 };
 export type SnapActionHandlers = {
     submit: (target: string, inputs: Record<string, JsonValue>) => void;
-    open_url: (target: string, options?: {
-        isSnap?: boolean;
-    }) => void;
+    open_url: (target: string) => void;
     open_mini_app: (target: string) => void;
     view_cast: (params: {
         hash: string;
@@ -41,9 +41,14 @@ export type SnapActionHandlers = {
         buyToken?: string;
     }) => void;
 };
-export declare function SnapView({ snap, handlers, loading, appearance, }: {
+export declare function SnapCard({ snap, handlers, loading, appearance, maxWidth, showOverflowWarning, onValidationError, validationErrorFallback, }: {
     snap: SnapPage;
     handlers: SnapActionHandlers;
     loading?: boolean;
     appearance?: "light" | "dark";
+    maxWidth?: number;
+    /** When true, extends to 700px and shows a warning overlay below 500px. When false, clips at 500px. Only applies to v2 snaps. */
+    showOverflowWarning?: boolean;
+    onValidationError?: (result: ValidationResult) => void;
+    validationErrorFallback?: ReactNode;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/react/index.js

@@ -1,231 +1,12 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { snapJsonRenderCatalog } from "../ui/index.js";
-import { SnapCatalogView } from "./catalog-renderer.js";
-import { SnapPreviewAccentProvider } from "./accent-context.js";
-import { resolveSnapPaletteHex } from "./lib/resolve-palette-hex.js";
-import { snapPreviewPrimaryCssProperties } from "./lib/preview-primary-css.js";
-import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
-// ─── Internal helpers ──────────────────────────────────
-function applyStatePaths(model, changes) {
-    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 { jsx as _jsx } from "react/jsx-runtime";
+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, }) {
+    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 }));
     }
-}
-const CONFETTI_COLORS = [
-    "#8B5CF6",
-    "#EC4899",
-    "#3B82F6",
-    "#10B981",
-    "#F59E0B",
-    "#EF4444",
-    "#06B6D4",
-];
-function ConfettiOverlay() {
-    const pieces = useMemo(() => Array.from({ length: 80 }, (_, i) => ({
-        id: i,
-        left: Math.random() * 100,
-        delay: Math.random() * 1.2,
-        duration: 2.5 + Math.random() * 2,
-        color: CONFETTI_COLORS[Math.floor(Math.random() * CONFETTI_COLORS.length)],
-        size: 6 + Math.random() * 8,
-        rotation: Math.random() * 360,
-    })), []);
-    return (_jsxs("div", { style: {
-            position: "absolute",
-            inset: 0,
-            overflow: "hidden",
-            pointerEvents: "none",
-            zIndex: 20,
-        }, children: [pieces.map(({ id, left, delay, duration, color, size, rotation }) => (_jsx("div", { style: {
-                    position: "absolute",
-                    left: `${left}%`,
-                    top: -20,
-                    width: size,
-                    height: size * 0.6,
-                    backgroundColor: color,
-                    borderRadius: 2,
-                    transform: `rotate(${rotation}deg)`,
-                    animation: `confettiFall ${duration}s ease-in ${delay}s forwards`,
-                } }, id))), _jsx("style", { children: `@keyframes confettiFall{0%{top:-20px;opacity:1;transform:rotate(0deg) translateX(0)}50%{opacity:1}100%{top:110%;opacity:0;transform:rotate(720deg) translateX(${Math.random() > 0.5 ? "" : "-"}40px)}}` })] }));
-}
-function SnapLoadingOverlay({ appearance, accentHex, active, }) {
-    const isDark = appearance === "dark";
-    const tint = isDark ? "rgba(0, 0, 0, 0.1)" : "rgba(255, 255, 255, 0.2)";
-    const trackColor = isDark
-        ? "rgba(255, 255, 255, 0.12)"
-        : "rgba(15, 23, 42, 0.1)";
-    return (_jsxs("div", { style: {
-            position: "absolute",
-            inset: 0,
-            display: "flex",
-            alignItems: "center",
-            justifyContent: "center",
-            zIndex: 10,
-            background: tint,
-            backdropFilter: active ? "blur(10px) saturate(1.05)" : "none",
-            WebkitBackdropFilter: active ? "blur(10px) saturate(1.05)" : "none",
-            opacity: active ? 1 : 0,
-            pointerEvents: active ? "auto" : "none",
-            transition: "opacity 0.28s ease, backdrop-filter 0.28s ease",
-        }, "aria-hidden": !active, "aria-busy": active ? true : undefined, "aria-live": active ? "polite" : undefined, "aria-label": active ? "Loading" : undefined, children: [_jsx("div", { "data-snap-loading-spinner": true, style: {
-                    width: 30,
-                    height: 30,
-                    borderRadius: "50%",
-                    border: `2.5px solid ${trackColor}`,
-                    borderTopColor: accentHex,
-                    opacity: 0.88,
-                    animation: "snapViewSpin 0.75s linear infinite",
-                    flexShrink: 0,
-                } }), _jsx("style", { children: `
-        @keyframes snapViewSpin {
-          to { transform: rotate(360deg); }
-        }
-        @media (prefers-reduced-motion: reduce) {
-          [data-snap-loading-spinner] {
-            animation: none;
-            border-top-color: ${accentHex};
-            opacity: 0.75;
-          }
-        }
-      ` })] }));
-}
-const PALETTE = [
-    "gray",
-    "blue",
-    "red",
-    "amber",
-    "green",
-    "teal",
-    "purple",
-    "pink",
-];
-// ─── SnapView ──────────────────────────────────────────
-export function SnapView({ snap, handlers, loading = false, appearance = "dark", }) {
-    const spec = snap.ui;
-    const initialState = useMemo(() => spec.state ?? { inputs: {} }, [spec]);
-    const stateRef = useRef(initialState);
-    useEffect(() => {
-        stateRef.current = {
-            inputs: {
-                ...(initialState.inputs ?? {}),
-            },
-            theme: {
-                ...(initialState.theme ?? {}),
-            },
-        };
-    }, [initialState]);
-    useEffect(() => {
-        const result = snapJsonRenderCatalog.validate(spec);
-        if (!result.success) {
-            // eslint-disable-next-line no-console
-            console.warn("[SnapView] catalog validation issues:", result.error);
-        }
-    }, [spec]);
-    const [pageKey, setPageKey] = useState(0);
-    useEffect(() => {
-        setPageKey((k) => k + 1);
-    }, [spec]);
-    const showConfetti = snap.effects?.includes("confetti");
-    // Increment key each time a new snap with confetti arrives so the overlay
-    // unmounts/remounts and restarts its animation on every trigger.
-    const confettiEpochRef = useRef(0);
-    const lastConfettiSnapRef = useRef(null);
-    if (showConfetti && snap !== lastConfettiSnapRef.current) {
-        confettiEpochRef.current++;
-        lastConfettiSnapRef.current = snap;
-    }
-    const accentName = snap.theme?.accent ?? "purple";
-    const accentHex = useMemo(() => resolveSnapPaletteHex(accentName, appearance), [accentName, appearance]);
-    const previewSurfaceStyle = useMemo(() => {
-        const vars = {};
-        for (const c of PALETTE)
-            vars[`--snap-color-${c}`] = resolveSnapPaletteHex(c, appearance);
-        return {
-            ...snapPreviewPrimaryCssProperties(accentName, appearance),
-            ...vars,
-        };
-    }, [accentName, appearance]);
-    const handleAction = useCallback((name, params) => {
-        const inputs = (stateRef.current.inputs ?? {});
-        const p = (params ?? {});
-        switch (name) {
-            case "submit":
-                handlers.submit(String(p.target ?? ""), inputs);
-                break;
-            case "open_url":
-                handlers.open_url(String(p.target ?? ""), {
-                    isSnap: p.isSnap === true,
-                });
-                break;
-            case "open_mini_app":
-                handlers.open_mini_app(String(p.target ?? ""));
-                break;
-            case "view_cast":
-                handlers.view_cast({ hash: String(p.hash ?? "") });
-                break;
-            case "view_profile":
-                handlers.view_profile({ fid: Number(p.fid ?? 0) });
-                break;
-            case "compose_cast":
-                handlers.compose_cast({
-                    text: p.text ? String(p.text) : undefined,
-                    channelKey: p.channelKey ? String(p.channelKey) : undefined,
-                    embeds: Array.isArray(p.embeds)
-                        ? p.embeds
-                        : undefined,
-                });
-                break;
-            case "view_token":
-                handlers.view_token({ token: String(p.token ?? "") });
-                break;
-            case "send_token":
-                handlers.send_token({
-                    token: String(p.token ?? ""),
-                    amount: p.amount ? String(p.amount) : undefined,
-                    recipientFid: p.recipientFid ? Number(p.recipientFid) : undefined,
-                    recipientAddress: p.recipientAddress
-                        ? String(p.recipientAddress)
-                        : undefined,
-                });
-                break;
-            case "swap_token":
-                handlers.swap_token({
-                    sellToken: p.sellToken ? String(p.sellToken) : undefined,
-                    buyToken: p.buyToken ? String(p.buyToken) : undefined,
-                });
-                break;
-            default:
-                break;
-        }
-    }, [handlers]);
-    return (_jsxs("div", { style: { position: "relative", width: "100%" }, children: [showConfetti && (_jsx(ConfettiOverlay, {}, `confetti-${confettiEpochRef.current}`)), _jsx(SnapLoadingOverlay, { appearance: appearance, accentHex: accentHex, active: loading }), _jsx("div", { style: previewSurfaceStyle, children: _jsx(SnapPreviewAccentProvider, { pageAccent: snap.theme?.accent, appearance: appearance, children: _jsx(SnapCatalogView, { spec: spec, state: initialState, loading: false, onStateChange: (changes) => {
-                            applyStatePaths(stateRef.current, changes);
-                        }, onAction: handleAction }, pageKey) }) })] }));
+    return (_jsx(SnapCardV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance, maxWidth: maxWidth }));
 }

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

@@ -0,0 +1,11 @@
+import type { SnapActionHandlers, SnapPage } from "./index.js";
+export declare function applyStatePaths(model: Record<string, unknown>, changes: {
+    path: string;
+    value: unknown;
+}[] | Record<string, unknown>): void;
+export declare function SnapViewCore({ snap, handlers, loading, appearance, }: {
+    snap: SnapPage;
+    handlers: SnapActionHandlers;
+    loading?: boolean;
+    appearance?: "light" | "dark";
+}): import("react/jsx-runtime").JSX.Element;

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

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

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

@@ -0,0 +1,14 @@
+import type { SnapPage, SnapActionHandlers } from "../index.js";
+export declare function SnapViewV1({ snap, handlers, loading, appearance, }: {
+    snap: SnapPage;
+    handlers: SnapActionHandlers;
+    loading?: boolean;
+    appearance?: "light" | "dark";
+}): import("react/jsx-runtime").JSX.Element;
+export declare function SnapCardV1({ snap, handlers, loading, appearance, maxWidth, }: {
+    snap: SnapPage;
+    handlers: SnapActionHandlers;
+    loading?: boolean;
+    appearance?: "light" | "dark";
+    maxWidth?: number;
+}): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,9 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { SnapViewCore } from "../snap-view-core.js";
+export function SnapViewV1({ snap, handlers, loading = false, appearance = "dark", }) {
+    return (_jsx(SnapViewCore, { snap: snap, handlers: handlers, loading: loading, appearance: appearance }));
+}
+export function SnapCardV1({ snap, handlers, loading = false, appearance = "dark", maxWidth = 480, }) {
+    return (_jsx("div", { style: { position: "relative", width: "100%", maxWidth }, children: _jsx(SnapViewV1, { snap: snap, handlers: handlers, loading: loading, appearance: appearance }) }));
+}

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

@@ -0,0 +1,21 @@
+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, }: {
+    snap: SnapPage;
+    handlers: SnapActionHandlers;
+    loading?: boolean;
+    appearance?: "light" | "dark";
+    onValidationError?: (result: ValidationResult) => void;
+    validationErrorFallback?: ReactNode;
+}): import("react/jsx-runtime").JSX.Element | null;
+export declare function SnapCardV2({ snap, handlers, loading, appearance, maxWidth, showOverflowWarning, onValidationError, validationErrorFallback, }: {
+    snap: SnapPage;
+    handlers: SnapActionHandlers;
+    loading?: boolean;
+    appearance?: "light" | "dark";
+    maxWidth?: number;
+    showOverflowWarning?: boolean;
+    onValidationError?: (result: ValidationResult) => void;
+    validationErrorFallback?: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;