@farcaster/snap 2.3.0 → 2.4.0

package/dist/colors.d.ts

@@ -34,6 +34,14 @@ export declare function resolveSnapColorHex(color: string | undefined, opts: {
     accentHex: string;
     appearance: "light" | "dark";
 }): string;
+/**
+ * Pick a readable text color for a given hex background.
+ *
+ * Uses WCAG relative luminance with a 0.5 threshold. Returns `rgba(...)` so
+ * callers can soften the text against the background — defaults to 0.8 alpha
+ * to let a hint of the cell color bleed through.
+ */
+export declare function readableTextOnHex(hex: string, alpha?: number): string;
 /** Light-mode hex for each palette color (emulator / reference client). */
 export declare const PALETTE_LIGHT_HEX: Record<PaletteColor, string>;
 /** Dark-mode hex for each palette color (reference). */

package/dist/colors.js

@@ -54,6 +54,27 @@ export function resolveSnapColorHex(color, opts) {
     }
     return opts.accentHex;
 }
+/**
+ * Pick a readable text color for a given hex background.
+ *
+ * Uses WCAG relative luminance with a 0.5 threshold. Returns `rgba(...)` so
+ * callers can soften the text against the background — defaults to 0.8 alpha
+ * to let a hint of the cell color bleed through.
+ */
+export function readableTextOnHex(hex, alpha = 0.8) {
+    const m = /^#([0-9a-fA-F]{6})$/.exec(hex.trim());
+    if (!m)
+        return `rgba(0,0,0,${alpha})`;
+    const n = Number.parseInt(m[1], 16);
+    const toLin = (c) => {
+        const s = c / 255;
+        return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+    };
+    const L = 0.2126 * toLin((n >> 16) & 0xff) +
+        0.7152 * toLin((n >> 8) & 0xff) +
+        0.0722 * toLin(n & 0xff);
+    return L >= 0.5 ? `rgba(0,0,0,${alpha})` : `rgba(255,255,255,${alpha})`;
+}
 /** Light-mode hex for each palette color (emulator / reference client). */
 export const PALETTE_LIGHT_HEX = {
     gray: "#6E6A86",

package/dist/constants.d.ts

@@ -5,7 +5,7 @@ export declare const SUPPORTED_SPEC_VERSIONS: readonly ["1.0", "2.0"];
 export type SpecVersion = (typeof SUPPORTED_SPEC_VERSIONS)[number];
 export declare const SNAP_PAYLOAD_HEADER: "X-Snap-Payload";
 export declare const MEDIA_TYPE: "application/vnd.farcaster.snap+json";
-export declare const EFFECT_VALUES: readonly ["confetti"];
+export declare const EFFECT_VALUES: readonly ["confetti", "fireworks"];
 export declare const POST_GRID_TAP_KEY: "grid_tap";
 export declare const GRID_MIN_COLS = 2;
 export declare const GRID_MAX_COLS = 32;

package/dist/constants.js

@@ -7,7 +7,7 @@ export const SUPPORTED_SPEC_VERSIONS = [
 ];
 export const SNAP_PAYLOAD_HEADER = "X-Snap-Payload";
 export const MEDIA_TYPE = "application/vnd.farcaster.snap+json";
-export const EFFECT_VALUES = ["confetti"];
+export const EFFECT_VALUES = ["confetti", "fireworks"];
 // ─── Pixel grid ────────────────────────────────────────
 export const POST_GRID_TAP_KEY = "grid_tap";
 export const GRID_MIN_COLS = 2;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export type { Spec as SnapSpec, UIElement as SnapUIElement, } from "@json-render/core";
 export { SPEC_VERSION, SPEC_VERSION_1, SPEC_VERSION_2, SUPPORTED_SPEC_VERSIONS, type SpecVersion, SNAP_PAYLOAD_HEADER, 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, isSnapHexColorString, resolveSnapColorHex, type PaletteColor, } from "./colors.js";
+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";

package/dist/index.js

@@ -1,4 +1,4 @@
 export { SPEC_VERSION, SPEC_VERSION_1, SPEC_VERSION_2, SUPPORTED_SPEC_VERSIONS, SNAP_PAYLOAD_HEADER, 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, isSnapHexColorString, resolveSnapColorHex, } from "./colors.js";
+export { DEFAULT_THEME_ACCENT, PALETTE_COLOR, PALETTE_COLOR_ACCENT, PALETTE_COLOR_VALUES, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, isSnapHexColorString, readableTextOnHex, resolveSnapColorHex, } from "./colors.js";
 export { ACTION_TYPE_GET, ACTION_TYPE_POST, snapResponseSchema, payloadSchema, getPayloadSchema, } from "./schemas.js";
 export { validateSnapResponse } from "./validator.js";

package/dist/react/components/action-button.js

@@ -5,6 +5,7 @@ import { ExternalLink } from "lucide-react";
 import { Button } from "@neynar/ui/button";
 import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors.js";
+import { useSnapStackDirection } from "../stack-direction-context.js";
 import { ICON_MAP } from "./icon.js";
 function isExternalLinkAction(on) {
     if (!on)
@@ -24,6 +25,7 @@ export function SnapActionButton({ element, emit, }) {
     const [hovered, setHovered] = useState(false);
     const Icon = iconName ? ICON_MAP[iconName] : undefined;
     const showExternalIcon = isExternalLinkAction(element.on);
+    const inHorizontalStack = useSnapStackDirection() === "horizontal";
     const style = {
         cursor: "pointer",
         ...(isPrimary
@@ -40,5 +42,13 @@ export function SnapActionButton({ element, emit, }) {
                 borderColor: "transparent",
             }),
     };
-    return (_jsx("div", { className: "w-full min-w-0 flex-1", children: _jsxs(Button, { type: "button", variant: isPrimary ? "default" : "secondary", className: cn("w-full gap-2"), style: style, onClick: () => emit("press"), onPointerEnter: () => setHovered(true), onPointerLeave: () => setHovered(false), children: [Icon && _jsx(Icon, { size: 16 }), label, showExternalIcon && (_jsx(ExternalLink, { size: 14, style: { opacity: 0.6 } }))] }) }));
+    return (
+    /**
+     * In a horizontal stack, `flex-1` lets the wrapper share row width with peers.
+     * In a vertical stack, `flex-1` would silently grow the button to fill column
+     * height (1/N distribution when siblings also flex-grow); stick to `w-full`.
+     */
+    _jsx("div", { className: inHorizontalStack
+            ? "w-full min-w-0 flex-1"
+            : "w-full min-w-0", children: _jsxs(Button, { type: "button", variant: isPrimary ? "default" : "secondary", className: cn("w-full gap-2"), style: style, onClick: () => emit("press"), onPointerEnter: () => setHovered(true), onPointerLeave: () => setHovered(false), children: [Icon && _jsx(Icon, { size: 16 }), label, showExternalIcon && (_jsx(ExternalLink, { size: 14, style: { opacity: 0.6 } }))] }) }));
 }

package/dist/react/components/cell-grid.js

@@ -2,7 +2,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useStateStore } from "@json-render/react";
 import { cn } from "@neynar/ui/utils";
-import { POST_GRID_TAP_KEY } from "@farcaster/snap";
+import { POST_GRID_TAP_KEY, readableTextOnHex } from "@farcaster/snap";
 import { useSnapColors } from "../hooks/use-snap-colors.js";
 export function SnapCellGrid({ element: { props, on }, emit, }) {
     const { get, set } = useStateStore();
@@ -69,7 +69,9 @@ export function SnapCellGrid({ element: { props, on }, emit, }) {
         for (let c = 0; c < cols; c++) {
             const cell = cellMap.get(`${r},${c}`);
             const selected = interactive && isSelected(r, c);
-            const bg = cell?.color ? colors.colorHex(cell.color) : emptyCellBg;
+            const bgHex = cell?.color ? colors.colorHex(cell.color) : null;
+            const bg = bgHex ?? emptyCellBg;
+            const textColor = bgHex ? readableTextOnHex(bgHex) : colors.text;
             cellEls.push(_jsx("div", { role: interactive ? "button" : undefined, tabIndex: interactive ? 0 : undefined, onClick: interactive ? () => handleTap(r, c) : undefined, onKeyDown: interactive
                     ? (e) => {
                         if (e.key === "Enter" || e.key === " ") {
@@ -80,6 +82,7 @@ export function SnapCellGrid({ element: { props, on }, emit, }) {
                     : undefined, className: cn("flex items-center justify-center rounded text-xs font-semibold", interactive ? "cursor-pointer select-none" : "cursor-default"), style: {
                     height: rowHeight,
                     background: bg,
+                    color: textColor,
                     boxShadow: selected
                         ? `inset 0 0 0 1px ${colors.mode === "dark" ? "#000" : "#fff"}, inset 0 0 0 2px ${colors.mode === "dark" ? "#fff" : "#000"}`
                         : undefined,

package/dist/react/components/item.js

@@ -1,10 +1,15 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Item, ItemContent, ItemTitle, ItemDescription, ItemActions, } from "@neynar/ui/item";
+import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors.js";
+import { useSnapStackDirection } from "../stack-direction-context.js";
 export function SnapItem({ element: { props, children: childIds }, children, }) {
     const title = String(props.title ?? "");
     const description = props.description ? String(props.description) : undefined;
     const colors = useSnapColors();
-    return (_jsxs(Item, { className: "flex-1 py-1.5 px-2.5", children: [_jsxs(ItemContent, { className: "gap-0.5", children: [_jsx(ItemTitle, { style: { color: colors.text }, children: title }), description && (_jsx(ItemDescription, { className: "mt-0", style: { color: colors.textMuted }, children: description }))] }), childIds && childIds.length > 0 && _jsx(ItemActions, { children: children })] }));
+    const inHorizontalStack = useSnapStackDirection() === "horizontal";
+    return (_jsxs(Item, { className: cn("py-1.5 px-2.5", 
+        /** Horizontal: share width with peers. Vertical: don't fill column height. */
+        inHorizontalStack && "flex-1"), children: [_jsxs(ItemContent, { className: "gap-0.5", children: [_jsx(ItemTitle, { style: { color: colors.text }, children: title }), description && (_jsx(ItemDescription, { className: "mt-0", style: { color: colors.textMuted }, children: description }))] }), childIds && childIds.length > 0 && _jsx(ItemActions, { children: children })] }));
 }

package/dist/react/components/progress.js

@@ -1,11 +1,16 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors.js";
+import { useSnapStackDirection } from "../stack-direction-context.js";
 export function SnapProgress({ element: { props }, }) {
     const colors = useSnapColors();
     const value = Number(props.value ?? 0);
     const max = Math.max(1, Number(props.max ?? 100));
     const percent = Math.min(100, Math.max(0, (value / max) * 100));
     const label = props.label ? String(props.label) : null;
-    return (_jsxs("div", { className: "flex w-full flex-1 flex-col gap-1", children: [label && (_jsx("span", { className: "text-xs", style: { color: colors.textMuted }, children: label })), _jsx("div", { className: "h-2.5 w-full overflow-hidden rounded-full", style: { backgroundColor: colors.muted }, children: _jsx("div", { className: "h-full rounded-full transition-all", style: { width: `${percent}%`, backgroundColor: colors.accent } }) })] }));
+    const inHorizontalStack = useSnapStackDirection() === "horizontal";
+    return (_jsxs("div", { className: cn("flex w-full flex-col gap-1", 
+        /** Horizontal: share width with peers. Vertical: don't fill column height. */
+        inHorizontalStack && "flex-1"), children: [label && (_jsx("span", { className: "text-xs", style: { color: colors.textMuted }, children: label })), _jsx("div", { className: "h-2.5 w-full overflow-hidden rounded-full", style: { backgroundColor: colors.muted }, children: _jsx("div", { className: "h-full rounded-full transition-all", style: { width: `${percent}%`, backgroundColor: colors.accent } }) })] }));
 }

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

@@ -47,33 +47,119 @@ const CONFETTI_COLORS = [
     "#EF4444",
     "#06B6D4",
 ];
+const FIREWORK_COLORS = [
+    "#FFD700",
+    "#FF6B6B",
+    "#4ECDC4",
+    "#C4A7E7",
+    "#F6C177",
+    "#EBBCBA",
+    "#9CCFD8",
+    "#fff",
+];
 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,
-    })), []);
+    const pieces = useMemo(() => Array.from({ length: 80 }, (_, i) => {
+        const driftX = (Math.random() - 0.5) * 120;
+        return {
+            id: i,
+            left: Math.random() * 100,
+            delay: Math.random() * 1.2,
+            duration: 2.8 + Math.random() * 1.8,
+            color: CONFETTI_COLORS[Math.floor(Math.random() * CONFETTI_COLORS.length)],
+            size: 6 + Math.random() * 8,
+            rotation: Math.random() * 360,
+            isCircle: Math.random() > 0.6,
+            driftX,
+            driftMid: -driftX * 0.4,
+        };
+    }), []);
     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: {
+        }, children: [pieces.map(({ id, left, delay, duration, color, size, rotation, isCircle, driftX, driftMid }) => (_jsx("div", { style: {
                     position: "absolute",
                     left: `${left}%`,
                     top: -20,
                     width: size,
-                    height: size * 0.6,
+                    height: isCircle ? size : size * 0.5,
                     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)}}` })] }));
+                    borderRadius: isCircle ? "50%" : 2,
+                    transform: `rotateZ(${rotation}deg)`,
+                    animation: `confettiFall ${duration}s cubic-bezier(0.25,0,0.75,1) ${delay}s forwards`,
+                    "--dx": `${driftX}px`,
+                    "--dm": `${driftMid}px`,
+                } }, id))), _jsx("style", { children: `@keyframes confettiFall{
+        0%  {top:-20px;opacity:1;transform:rotateZ(0deg) rotateY(0deg) translateX(0)}
+        20% {transform:rotateZ(144deg) rotateY(60deg) translateX(var(--dm))}
+        40% {transform:rotateZ(288deg) rotateY(120deg) translateX(0)}
+        60% {opacity:1;transform:rotateZ(432deg) rotateY(200deg) translateX(calc(-1 * var(--dm)))}
+        80% {transform:rotateZ(576deg) rotateY(280deg) translateX(var(--dx))}
+        100%{top:110%;opacity:0;transform:rotateZ(720deg) rotateY(360deg) translateX(var(--dx))}
+      }` })] }));
+}
+function FireworksOverlay() {
+    const bursts = useMemo(() => Array.from({ length: 5 }, (_, b) => ({
+        id: b,
+        x: 15 + Math.random() * 70,
+        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 dist = 55 + Math.random() * 60;
+            return {
+                id: p,
+                vx: Math.cos(angle) * dist,
+                vy: Math.sin(angle) * dist,
+                color: FIREWORK_COLORS[Math.floor(Math.random() * FIREWORK_COLORS.length)],
+                size: 3 + Math.random() * 3,
+            };
+        }),
+    })), []);
+    return (_jsxs("div", { style: {
+            position: "absolute",
+            inset: 0,
+            overflow: "hidden",
+            pointerEvents: "none",
+            zIndex: 20,
+        }, children: [bursts.map(({ id: bid, x, y, delay, particles }) => (_jsxs("div", { children: [_jsx("div", { style: {
+                            position: "absolute",
+                            left: `${x}%`,
+                            top: `${y}%`,
+                            width: 12,
+                            height: 12,
+                            borderRadius: "50%",
+                            backgroundColor: "#fff",
+                            transform: "translate(-50%,-50%)",
+                            animation: `fwFlash 0.4s ease-out ${delay}s both`,
+                            opacity: 0,
+                        } }), particles.map(({ id: pid, vx, vy, color, size }) => (_jsx("div", { style: {
+                            position: "absolute",
+                            left: `${x}%`,
+                            top: `${y}%`,
+                            width: size,
+                            height: size,
+                            borderRadius: "50%",
+                            backgroundColor: color,
+                            transform: "translate(-50%,-50%)",
+                            animation: `fwBurst 1s cubic-bezier(0.2,0,0.8,1) ${delay}s forwards`,
+                            opacity: 0,
+                            "--vx": `${vx}px`,
+                            "--vy": `${vy}px`,
+                        } }, pid)))] }, bid))), _jsx("style", { children: `
+        @keyframes fwFlash{
+          0%  {opacity:0;transform:translate(-50%,-50%) scale(0)}
+          25% {opacity:1;transform:translate(-50%,-50%) scale(2.5)}
+          100%{opacity:0;transform:translate(-50%,-50%) scale(5)}
+        }
+        @keyframes fwBurst{
+          0%  {opacity:1;transform:translate(-50%,-50%) translate(0,0) scale(1)}
+          65% {opacity:1}
+          100%{opacity:0;transform:translate(-50%,-50%) translate(var(--vx),var(--vy)) scale(0)}
+        }
+      ` })] }));
 }
 export function SnapLoadingOverlay({ appearance, accentHex, active, }) {
     const isDark = appearance === "dark";
@@ -156,11 +242,15 @@ export function SnapViewCore({ snap, handlers, loading = false, appearance = "da
         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);
     useEffect(() => {
         if (showConfetti)
             setConfettiKey((k) => k + 1);
-    }, [showConfetti, snap]);
+        if (showFireworks)
+            setFireworksKey((k) => k + 1);
+    }, [showConfetti, showFireworks, snap]);
     const accentName = snap.theme?.accent ?? "purple";
     const accentHex = useMemo(() => resolveSnapPaletteHex(accentName, appearance), [accentName, appearance]);
     const previewSurfaceStyle = useMemo(() => {
@@ -226,7 +316,7 @@ export function SnapViewCore({ snap, handlers, loading = false, appearance = "da
                 break;
         }
     }, [handlers]);
-    return (_jsxs("div", { style: { position: "relative", width: "100%" }, children: [showConfetti && _jsx(ConfettiOverlay, {}, confettiKey), 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(SnapCatalogView, { spec: spec, state: initialState, loading: false, onStateChange: (changes) => {
+    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(SnapCatalogView, { spec: spec, state: initialState, loading: false, onStateChange: (changes) => {
                             applyStatePaths(stateRef.current, changes);
                         }, onAction: handleAction }, pageKey) }) })] }));
 }

package/dist/react-native/components/snap-cell-grid.js

@@ -3,7 +3,7 @@ import { StyleSheet, Text, View, Pressable } from "react-native";
 import { useStateStore } from "@json-render/react-native";
 import { useSnapPalette } from "../use-snap-palette.js";
 import { useSnapTheme } from "../theme.js";
-import { POST_GRID_TAP_KEY } from "@farcaster/snap";
+import { POST_GRID_TAP_KEY, readableTextOnHex } from "@farcaster/snap";
 export function SnapCellGrid({ element, emit, }) {
     const { props } = element;
     const on = element.on;
@@ -75,8 +75,10 @@ export function SnapCellGrid({ element, emit, }) {
         for (let c = 0; c < cols; c++) {
             const cell = cellMap.get(`${r},${c}`);
             const selected = interactive && isSelected(r, c);
-            const bg = cell?.color ? hex(cell.color) : emptyCellBg;
-            const cellContent = cell?.content ? (_jsx(Text, { style: [styles.cellText, { color: colors.textPrimary }], children: cell.content })) : null;
+            const bgHex = cell?.color ? hex(cell.color) : null;
+            const bg = bgHex ?? emptyCellBg;
+            const textColor = bgHex ? readableTextOnHex(bgHex) : colors.text;
+            const cellContent = cell?.content ? (_jsx(Text, { style: [styles.cellText, { color: textColor }], children: cell.content })) : null;
             // Two-tone ring: outer View with contrasting border, inner View with inverse border
             const cellView = selected ? (_jsx(View, { style: [styles.cell, { height: rowHeight, borderWidth: 1, borderColor: ringOuter, borderRadius: 4 }], children: _jsx(View, { style: [
                         styles.innerCell,

package/dist/react-native/fireworks-overlay.d.ts

@@ -0,0 +1 @@
+export declare function FireworksOverlay(): import("react").JSX.Element;

package/dist/react-native/fireworks-overlay.js

@@ -0,0 +1,125 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Animated, StyleSheet, View, useWindowDimensions } from "react-native";
+const FIREWORK_COLORS = [
+    "#FFD700",
+    "#FF6B6B",
+    "#4ECDC4",
+    "#C4A7E7",
+    "#F6C177",
+    "#EBBCBA",
+    "#9CCFD8",
+    "#fff",
+];
+const BURST_COUNT = 5;
+const PARTICLE_COUNT = 24;
+function FireworkBurst({ burst }) {
+    const flashAnim = useRef(new Animated.Value(0)).current;
+    const burstAnim = useRef(new Animated.Value(0)).current;
+    useEffect(() => {
+        const composite = Animated.parallel([
+            Animated.timing(flashAnim, {
+                toValue: 1,
+                duration: 400,
+                useNativeDriver: true,
+            }),
+            Animated.timing(burstAnim, {
+                toValue: 1,
+                duration: 1000,
+                useNativeDriver: true,
+            }),
+        ]);
+        composite.start();
+        return () => composite.stop();
+    }, [flashAnim, burstAnim]);
+    const flashOpacity = flashAnim.interpolate({
+        inputRange: [0, 0.25, 1],
+        outputRange: [0, 1, 0],
+    });
+    const flashScale = flashAnim.interpolate({
+        inputRange: [0, 0.25, 1],
+        outputRange: [0, 2.5, 5],
+    });
+    return (_jsxs(_Fragment, { children: [_jsx(Animated.View, { style: [
+                    styles.flash,
+                    {
+                        left: burst.x - 6,
+                        top: burst.y - 6,
+                        opacity: flashOpacity,
+                        transform: [{ scale: flashScale }],
+                    },
+                ] }), burst.particles.map((p) => {
+                const opacity = burstAnim.interpolate({
+                    inputRange: [0, 0.65, 1],
+                    outputRange: [1, 1, 0],
+                });
+                const translateX = burstAnim.interpolate({
+                    inputRange: [0, 1],
+                    outputRange: [0, p.vx],
+                });
+                const translateY = burstAnim.interpolate({
+                    inputRange: [0, 1],
+                    outputRange: [0, p.vy],
+                });
+                const scale = burstAnim.interpolate({
+                    inputRange: [0, 1],
+                    outputRange: [1, 0],
+                });
+                return (_jsx(Animated.View, { style: [
+                        styles.particle,
+                        {
+                            left: burst.x - p.size / 2,
+                            top: burst.y - p.size / 2,
+                            width: p.size,
+                            height: p.size,
+                            backgroundColor: p.color,
+                            opacity,
+                            transform: [{ translateX }, { translateY }, { scale }],
+                        },
+                    ] }, p.id));
+            })] }));
+}
+export function FireworksOverlay() {
+    const { width, height } = useWindowDimensions();
+    const bursts = useMemo(() => Array.from({ length: BURST_COUNT }, (_, b) => ({
+        id: b,
+        x: (0.15 + Math.random() * 0.7) * width,
+        y: (0.1 + Math.random() * 0.5) * height,
+        delay: b * 500 + Math.random() * 200,
+        particles: Array.from({ length: PARTICLE_COUNT }, (_, p) => {
+            const angle = (p / PARTICLE_COUNT) * Math.PI * 2 + (Math.random() - 0.5) * 0.2;
+            const dist = 55 + Math.random() * 60;
+            return {
+                id: p,
+                vx: Math.cos(angle) * dist,
+                vy: Math.sin(angle) * dist,
+                color: FIREWORK_COLORS[Math.floor(Math.random() * FIREWORK_COLORS.length)],
+                size: 3 + Math.random() * 3,
+            };
+        }),
+    })), 
+    // stable on mount
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    []);
+    const [mountedBursts, setMountedBursts] = useState([]);
+    useEffect(() => {
+        const timers = bursts.map((burst, b) => setTimeout(() => {
+            setMountedBursts((prev) => [...prev, b]);
+        }, burst.delay));
+        return () => timers.forEach(clearTimeout);
+    }, [bursts]);
+    return (_jsx(View, { style: StyleSheet.absoluteFill, pointerEvents: "none", children: mountedBursts.map((b) => (_jsx(FireworkBurst, { burst: bursts[b] }, b))) }));
+}
+const styles = StyleSheet.create({
+    flash: {
+        position: "absolute",
+        width: 12,
+        height: 12,
+        borderRadius: 6,
+        backgroundColor: "#fff",
+    },
+    particle: {
+        position: "absolute",
+        borderRadius: 999,
+    },
+});

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

@@ -2,6 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { snapJsonRenderCatalog } from "@farcaster/snap/ui";
 import { SnapCatalogView } from "./catalog-renderer.js";
 import { ConfettiOverlay } from "./confetti-overlay.js";
+import { FireworksOverlay } from "./fireworks-overlay.js";
 import { useSnapTheme } from "./theme.js";
 import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
 import { ActivityIndicator, StyleSheet, View } from "react-native";
@@ -81,11 +82,15 @@ export function SnapViewCoreInner({ snap, handlers, loading = false, loadingOver
         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);
     useEffect(() => {
         if (showConfetti)
             setConfettiKey((k) => k + 1);
-    }, [showConfetti, snap]);
+        if (showFireworks)
+            setFireworksKey((k) => k + 1);
+    }, [showConfetti, showFireworks, snap]);
     const handlersRef = useRef(handlers);
     handlersRef.current = handlers;
     const handleAction = useCallback((name, params) => {
@@ -147,7 +152,7 @@ export function SnapViewCoreInner({ snap, handlers, loading = false, loadingOver
                     : loadingOverlay
                 : null, _jsx(SnapCatalogView, { spec: spec, state: initialState, loading: false, onStateChange: (changes) => {
                     applyStatePaths(stateRef.current, changes);
-                }, onAction: handleAction }, pageKey), showConfetti && _jsx(ConfettiOverlay, {}, confettiKey)] }));
+                }, onAction: handleAction }, pageKey), showConfetti && _jsx(ConfettiOverlay, {}, confettiKey), showFireworks && _jsx(FireworksOverlay, {}, fireworksKey)] }));
 }
 export function SnapLoadingOverlay({ appearance, accentHex, }) {
     return (_jsx(View, { style: [

package/dist/schemas.d.ts

@@ -30,6 +30,7 @@ export declare const snapResponseSchema: z.ZodObject<{
     }, z.core.$strict>>>;
     effects: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         confetti: "confetti";
+        fireworks: "fireworks";
     }>>>;
     ui: z.ZodCustom<Spec, Spec>;
 }, z.core.$strict>;

package/package.json

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

package/src/colors.ts

@@ -65,6 +65,28 @@ export function resolveSnapColorHex(
   return opts.accentHex;
 }
 
+/**
+ * Pick a readable text color for a given hex background.
+ *
+ * Uses WCAG relative luminance with a 0.5 threshold. Returns `rgba(...)` so
+ * callers can soften the text against the background — defaults to 0.8 alpha
+ * to let a hint of the cell color bleed through.
+ */
+export function readableTextOnHex(hex: string, alpha = 0.8): string {
+  const m = /^#([0-9a-fA-F]{6})$/.exec(hex.trim());
+  if (!m) return `rgba(0,0,0,${alpha})`;
+  const n = Number.parseInt(m[1], 16);
+  const toLin = (c: number) => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  const L =
+    0.2126 * toLin((n >> 16) & 0xff) +
+    0.7152 * toLin((n >> 8) & 0xff) +
+    0.0722 * toLin(n & 0xff);
+  return L >= 0.5 ? `rgba(0,0,0,${alpha})` : `rgba(255,255,255,${alpha})`;
+}
+
 /** Light-mode hex for each palette color (emulator / reference client). */
 export const PALETTE_LIGHT_HEX: Record<PaletteColor, string> = {
   gray: "#6E6A86",

package/src/constants.ts

@@ -11,7 +11,7 @@ export const SNAP_PAYLOAD_HEADER = "X-Snap-Payload" as const;
 
 export const MEDIA_TYPE = "application/vnd.farcaster.snap+json" as const;
 
-export const EFFECT_VALUES = ["confetti"] as const;
+export const EFFECT_VALUES = ["confetti", "fireworks"] as const;
 
 // ─── Pixel grid ────────────────────────────────────────
 export const POST_GRID_TAP_KEY = "grid_tap" as const;

package/src/index.ts

@@ -25,6 +25,7 @@ export {
   PALETTE_LIGHT_HEX,
   PALETTE_DARK_HEX,
   isSnapHexColorString,
+  readableTextOnHex,
   resolveSnapColorHex,
   type PaletteColor,
 } from "./colors";

package/src/react/components/action-button.tsx

@@ -5,6 +5,7 @@ import { ExternalLink } from "lucide-react";
 import { Button } from "@neynar/ui/button";
 import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors";
+import { useSnapStackDirection } from "../stack-direction-context";
 import { ICON_MAP } from "./icon";
 
 function isExternalLinkAction(
@@ -38,6 +39,7 @@ export function SnapActionButton({
 
   const Icon = iconName ? ICON_MAP[iconName] : undefined;
   const showExternalIcon = isExternalLinkAction(element.on);
+  const inHorizontalStack = useSnapStackDirection() === "horizontal";
 
   const style = {
     cursor: "pointer" as const,
@@ -57,7 +59,18 @@ export function SnapActionButton({
   };
 
   return (
-    <div className="w-full min-w-0 flex-1">
+    /**
+     * In a horizontal stack, `flex-1` lets the wrapper share row width with peers.
+     * In a vertical stack, `flex-1` would silently grow the button to fill column
+     * height (1/N distribution when siblings also flex-grow); stick to `w-full`.
+     */
+    <div
+      className={
+        inHorizontalStack
+          ? "w-full min-w-0 flex-1"
+          : "w-full min-w-0"
+      }
+    >
       <Button
         type="button"
         variant={isPrimary ? "default" : "secondary"}

package/src/react/components/cell-grid.tsx

@@ -3,7 +3,7 @@
 import type { ReactNode } from "react";
 import { useStateStore } from "@json-render/react";
 import { cn } from "@neynar/ui/utils";
-import { POST_GRID_TAP_KEY } from "@farcaster/snap";
+import { POST_GRID_TAP_KEY, readableTextOnHex } from "@farcaster/snap";
 import { useSnapColors } from "../hooks/use-snap-colors";
 
 export function SnapCellGrid({
@@ -85,7 +85,9 @@ export function SnapCellGrid({
     for (let c = 0; c < cols; c++) {
       const cell = cellMap.get(`${r},${c}`);
       const selected = interactive && isSelected(r, c);
-      const bg = cell?.color ? colors.colorHex(cell.color) : emptyCellBg;
+      const bgHex = cell?.color ? colors.colorHex(cell.color) : null;
+      const bg = bgHex ?? emptyCellBg;
+      const textColor = bgHex ? readableTextOnHex(bgHex) : colors.text;
 
       cellEls.push(
         <div
@@ -110,6 +112,7 @@ export function SnapCellGrid({
           style={{
             height: rowHeight,
             background: bg,
+            color: textColor,
             boxShadow: selected
               ? `inset 0 0 0 1px ${colors.mode === "dark" ? "#000" : "#fff"}, inset 0 0 0 2px ${colors.mode === "dark" ? "#fff" : "#000"}`
               : undefined,

package/src/react/components/item.tsx

@@ -7,7 +7,9 @@ import {
   ItemDescription,
   ItemActions,
 } from "@neynar/ui/item";
+import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors";
+import { useSnapStackDirection } from "../stack-direction-context";
 
 export function SnapItem({
   element: { props, children: childIds },
@@ -19,9 +21,16 @@ export function SnapItem({
   const title = String(props.title ?? "");
   const description = props.description ? String(props.description) : undefined;
   const colors = useSnapColors();
+  const inHorizontalStack = useSnapStackDirection() === "horizontal";
 
   return (
-    <Item className="flex-1 py-1.5 px-2.5">
+    <Item
+      className={cn(
+        "py-1.5 px-2.5",
+        /** Horizontal: share width with peers. Vertical: don't fill column height. */
+        inHorizontalStack && "flex-1",
+      )}
+    >
       <ItemContent className="gap-0.5">
         <ItemTitle style={{ color: colors.text }}>{title}</ItemTitle>
         {description && (

package/src/react/components/progress.tsx

@@ -1,6 +1,8 @@
 "use client";
 
+import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors";
+import { useSnapStackDirection } from "../stack-direction-context";
 
 export function SnapProgress({
   element: { props },
@@ -12,9 +14,16 @@ export function SnapProgress({
   const max = Math.max(1, Number(props.max ?? 100));
   const percent = Math.min(100, Math.max(0, (value / max) * 100));
   const label = props.label ? String(props.label) : null;
+  const inHorizontalStack = useSnapStackDirection() === "horizontal";
 
   return (
-    <div className="flex w-full flex-1 flex-col gap-1">
+    <div
+      className={cn(
+        "flex w-full flex-col gap-1",
+        /** Horizontal: share width with peers. Vertical: don't fill column height. */
+        inHorizontalStack && "flex-1",
+      )}
+    >
       {label && (
         <span className="text-xs" style={{ color: colors.textMuted }}>
           {label}

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

@@ -63,18 +63,106 @@ const CONFETTI_COLORS = [
   "#06B6D4",
 ];
 
+const FIREWORK_COLORS = [
+  "#FFD700",
+  "#FF6B6B",
+  "#4ECDC4",
+  "#C4A7E7",
+  "#F6C177",
+  "#EBBCBA",
+  "#9CCFD8",
+  "#fff",
+];
+
 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,
+      Array.from({ length: 80 }, (_, i) => {
+        const driftX = (Math.random() - 0.5) * 120;
+        return {
+          id: i,
+          left: Math.random() * 100,
+          delay: Math.random() * 1.2,
+          duration: 2.8 + Math.random() * 1.8,
+          color:
+            CONFETTI_COLORS[Math.floor(Math.random() * CONFETTI_COLORS.length)],
+          size: 6 + Math.random() * 8,
+          rotation: Math.random() * 360,
+          isCircle: Math.random() > 0.6,
+          driftX,
+          driftMid: -driftX * 0.4,
+        };
+      }),
+    [],
+  );
+
+  return (
+    <div
+      style={{
+        position: "absolute",
+        inset: 0,
+        overflow: "hidden",
+        pointerEvents: "none",
+        zIndex: 20,
+      }}
+    >
+      {pieces.map(
+        ({ id, left, delay, duration, color, size, rotation, isCircle, driftX, driftMid }) => (
+          <div
+            key={id}
+            style={
+              {
+                position: "absolute",
+                left: `${left}%`,
+                top: -20,
+                width: size,
+                height: isCircle ? size : size * 0.5,
+                backgroundColor: color,
+                borderRadius: isCircle ? "50%" : 2,
+                transform: `rotateZ(${rotation}deg)`,
+                animation: `confettiFall ${duration}s cubic-bezier(0.25,0,0.75,1) ${delay}s forwards`,
+                "--dx": `${driftX}px`,
+                "--dm": `${driftMid}px`,
+              } as CSSProperties
+            }
+          />
+        ),
+      )}
+      <style>{`@keyframes confettiFall{
+        0%  {top:-20px;opacity:1;transform:rotateZ(0deg) rotateY(0deg) translateX(0)}
+        20% {transform:rotateZ(144deg) rotateY(60deg) translateX(var(--dm))}
+        40% {transform:rotateZ(288deg) rotateY(120deg) translateX(0)}
+        60% {opacity:1;transform:rotateZ(432deg) rotateY(200deg) translateX(calc(-1 * var(--dm)))}
+        80% {transform:rotateZ(576deg) rotateY(280deg) translateX(var(--dx))}
+        100%{top:110%;opacity:0;transform:rotateZ(720deg) rotateY(360deg) translateX(var(--dx))}
+      }`}</style>
+    </div>
+  );
+}
+
+function FireworksOverlay() {
+  const bursts = useMemo(
+    () =>
+      Array.from({ length: 5 }, (_, b) => ({
+        id: b,
+        x: 15 + Math.random() * 70,
+        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 dist = 55 + Math.random() * 60;
+          return {
+            id: p,
+            vx: Math.cos(angle) * dist,
+            vy: Math.sin(angle) * dist,
+            color:
+              FIREWORK_COLORS[
+                Math.floor(Math.random() * FIREWORK_COLORS.length)
+              ],
+            size: 3 + Math.random() * 3,
+          };
+        }),
       })),
     [],
   );
@@ -89,25 +177,57 @@ function ConfettiOverlay() {
         zIndex: 20,
       }}
     >
-      {pieces.map(({ id, left, delay, duration, color, size, rotation }) => (
-        <div
-          key={id}
-          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`,
-          }}
-        />
+      {bursts.map(({ id: bid, x, y, delay, particles }) => (
+        <div key={bid}>
+          <div
+            style={{
+              position: "absolute",
+              left: `${x}%`,
+              top: `${y}%`,
+              width: 12,
+              height: 12,
+              borderRadius: "50%",
+              backgroundColor: "#fff",
+              transform: "translate(-50%,-50%)",
+              animation: `fwFlash 0.4s ease-out ${delay}s both`,
+              opacity: 0,
+            }}
+          />
+          {particles.map(({ id: pid, vx, vy, color, size }) => (
+            <div
+              key={pid}
+              style={
+                {
+                  position: "absolute",
+                  left: `${x}%`,
+                  top: `${y}%`,
+                  width: size,
+                  height: size,
+                  borderRadius: "50%",
+                  backgroundColor: color,
+                  transform: "translate(-50%,-50%)",
+                  animation: `fwBurst 1s cubic-bezier(0.2,0,0.8,1) ${delay}s forwards`,
+                  opacity: 0,
+                  "--vx": `${vx}px`,
+                  "--vy": `${vy}px`,
+                } as CSSProperties
+              }
+            />
+          ))}
+        </div>
       ))}
-      <style>{`@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)}}`}</style>
+      <style>{`
+        @keyframes fwFlash{
+          0%  {opacity:0;transform:translate(-50%,-50%) scale(0)}
+          25% {opacity:1;transform:translate(-50%,-50%) scale(2.5)}
+          100%{opacity:0;transform:translate(-50%,-50%) scale(5)}
+        }
+        @keyframes fwBurst{
+          0%  {opacity:1;transform:translate(-50%,-50%) translate(0,0) scale(1)}
+          65% {opacity:1}
+          100%{opacity:0;transform:translate(-50%,-50%) translate(var(--vx),var(--vy)) scale(0)}
+        }
+      `}</style>
     </div>
   );
 }
@@ -240,10 +360,13 @@ export function SnapViewCore({
   }, [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);
   useEffect(() => {
     if (showConfetti) setConfettiKey((k) => k + 1);
-  }, [showConfetti, snap]);
+    if (showFireworks) setFireworksKey((k) => k + 1);
+  }, [showConfetti, showFireworks, snap]);
 
   const accentName = snap.theme?.accent ?? "purple";
 
@@ -326,6 +449,7 @@ export function SnapViewCore({
   return (
     <div style={{ position: "relative", width: "100%" }}>
       {showConfetti && <ConfettiOverlay key={confettiKey} />}
+      {showFireworks && <FireworksOverlay key={fireworksKey} />}
       {loadingOverlay === undefined ? (
         <SnapLoadingOverlay
           appearance={appearance}

package/src/react-native/components/snap-cell-grid.tsx

@@ -3,7 +3,7 @@ import { StyleSheet, Text, View, Pressable } from "react-native";
 import { useStateStore } from "@json-render/react-native";
 import { useSnapPalette } from "../use-snap-palette";
 import { useSnapTheme } from "../theme";
-import { POST_GRID_TAP_KEY } from "@farcaster/snap";
+import { POST_GRID_TAP_KEY, readableTextOnHex } from "@farcaster/snap";
 
 export function SnapCellGrid({
   element,
@@ -89,10 +89,12 @@ export function SnapCellGrid({
     for (let c = 0; c < cols; c++) {
       const cell = cellMap.get(`${r},${c}`);
       const selected = interactive && isSelected(r, c);
-      const bg = cell?.color ? hex(cell.color) : emptyCellBg;
+      const bgHex = cell?.color ? hex(cell.color) : null;
+      const bg = bgHex ?? emptyCellBg;
+      const textColor = bgHex ? readableTextOnHex(bgHex) : colors.text;
 
       const cellContent = cell?.content ? (
-        <Text style={[styles.cellText, { color: colors.textPrimary }]}>
+        <Text style={[styles.cellText, { color: textColor }]}>
           {cell.content}
         </Text>
       ) : null;

package/src/react-native/fireworks-overlay.tsx

@@ -0,0 +1,176 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Animated, StyleSheet, View, useWindowDimensions } from "react-native";
+
+const FIREWORK_COLORS = [
+  "#FFD700",
+  "#FF6B6B",
+  "#4ECDC4",
+  "#C4A7E7",
+  "#F6C177",
+  "#EBBCBA",
+  "#9CCFD8",
+  "#fff",
+];
+
+const BURST_COUNT = 5;
+const PARTICLE_COUNT = 24;
+
+type BurstData = {
+  id: number;
+  x: number;
+  y: number;
+  particles: Array<{
+    id: number;
+    vx: number;
+    vy: number;
+    color: string;
+    size: number;
+  }>;
+};
+
+function FireworkBurst({ burst }: { burst: BurstData }) {
+  const flashAnim = useRef(new Animated.Value(0)).current;
+  const burstAnim = useRef(new Animated.Value(0)).current;
+
+  useEffect(() => {
+    const composite = Animated.parallel([
+      Animated.timing(flashAnim, {
+        toValue: 1,
+        duration: 400,
+        useNativeDriver: true,
+      }),
+      Animated.timing(burstAnim, {
+        toValue: 1,
+        duration: 1000,
+        useNativeDriver: true,
+      }),
+    ]);
+    composite.start();
+    return () => composite.stop();
+  }, [flashAnim, burstAnim]);
+
+  const flashOpacity = flashAnim.interpolate({
+    inputRange: [0, 0.25, 1],
+    outputRange: [0, 1, 0],
+  });
+  const flashScale = flashAnim.interpolate({
+    inputRange: [0, 0.25, 1],
+    outputRange: [0, 2.5, 5],
+  });
+
+  return (
+    <>
+      <Animated.View
+        style={[
+          styles.flash,
+          {
+            left: burst.x - 6,
+            top: burst.y - 6,
+            opacity: flashOpacity,
+            transform: [{ scale: flashScale }],
+          },
+        ]}
+      />
+      {burst.particles.map((p) => {
+        const opacity = burstAnim.interpolate({
+          inputRange: [0, 0.65, 1],
+          outputRange: [1, 1, 0],
+        });
+        const translateX = burstAnim.interpolate({
+          inputRange: [0, 1],
+          outputRange: [0, p.vx],
+        });
+        const translateY = burstAnim.interpolate({
+          inputRange: [0, 1],
+          outputRange: [0, p.vy],
+        });
+        const scale = burstAnim.interpolate({
+          inputRange: [0, 1],
+          outputRange: [1, 0],
+        });
+        return (
+          <Animated.View
+            key={p.id}
+            style={[
+              styles.particle,
+              {
+                left: burst.x - p.size / 2,
+                top: burst.y - p.size / 2,
+                width: p.size,
+                height: p.size,
+                backgroundColor: p.color,
+                opacity,
+                transform: [{ translateX }, { translateY }, { scale }],
+              },
+            ]}
+          />
+        );
+      })}
+    </>
+  );
+}
+
+export function FireworksOverlay() {
+  const { width, height } = useWindowDimensions();
+
+  const bursts = useMemo<(BurstData & { delay: number })[]>(
+    () =>
+      Array.from({ length: BURST_COUNT }, (_, b) => ({
+        id: b,
+        x: (0.15 + Math.random() * 0.7) * width,
+        y: (0.1 + Math.random() * 0.5) * height,
+        delay: b * 500 + Math.random() * 200,
+        particles: Array.from({ length: PARTICLE_COUNT }, (_, p) => {
+          const angle =
+            (p / PARTICLE_COUNT) * Math.PI * 2 + (Math.random() - 0.5) * 0.2;
+          const dist = 55 + Math.random() * 60;
+          return {
+            id: p,
+            vx: Math.cos(angle) * dist,
+            vy: Math.sin(angle) * dist,
+            color:
+              FIREWORK_COLORS[
+                Math.floor(Math.random() * FIREWORK_COLORS.length)
+              ]!,
+            size: 3 + Math.random() * 3,
+          };
+        }),
+      })),
+    // stable on mount
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  );
+
+  const [mountedBursts, setMountedBursts] = useState<number[]>([]);
+
+  useEffect(() => {
+    const timers = bursts.map((burst, b) =>
+      setTimeout(() => {
+        setMountedBursts((prev) => [...prev, b]);
+      }, burst.delay),
+    );
+    return () => timers.forEach(clearTimeout);
+  }, [bursts]);
+
+  return (
+    <View style={StyleSheet.absoluteFill} pointerEvents="none">
+      {mountedBursts.map((b) => (
+        <FireworkBurst key={b} burst={bursts[b]!} />
+      ))}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  flash: {
+    position: "absolute",
+    width: 12,
+    height: 12,
+    borderRadius: 6,
+    backgroundColor: "#fff",
+  },
+  particle: {
+    position: "absolute",
+    borderRadius: 999,
+  },
+});

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

@@ -2,6 +2,7 @@ import type { Spec } from "@json-render/core";
 import { snapJsonRenderCatalog } from "@farcaster/snap/ui";
 import { SnapCatalogView } from "./catalog-renderer";
 import { ConfettiOverlay } from "./confetti-overlay";
+import { FireworksOverlay } from "./fireworks-overlay";
 import { useSnapTheme } from "./theme";
 import {
   type ReactNode,
@@ -128,10 +129,13 @@ export function SnapViewCoreInner({
   }, [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);
   useEffect(() => {
     if (showConfetti) setConfettiKey((k) => k + 1);
-  }, [showConfetti, snap]);
+    if (showFireworks) setFireworksKey((k) => k + 1);
+  }, [showConfetti, showFireworks, snap]);
 
   const handlersRef = useRef(handlers);
   handlersRef.current = handlers;
@@ -213,6 +217,7 @@ export function SnapViewCoreInner({
         onAction={handleAction}
       />
       {showConfetti && <ConfettiOverlay key={confettiKey} />}
+      {showFireworks && <FireworksOverlay key={fireworksKey} />}
     </View>
   );
 }