@farcaster/snap 2.5.1 → 2.6.0

package/dist/constants.d.ts

@@ -13,6 +13,7 @@ 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 GRID_CELL_ASPECT_RATIO_VALUES: readonly ["auto", "square"];
+export declare const GRID_MAX_WIDTH_VALUES: readonly ["sm", "md", "lg"];
 export declare const MAX_ELEMENTS = 64;
 export declare const MAX_ROOT_CHILDREN = 7;
 export declare const MAX_CHILDREN = 6;

package/dist/constants.js

@@ -16,6 +16,7 @@ export const GRID_MIN_ROWS = 2;
 export const GRID_MAX_ROWS = 16;
 export const GRID_GAP_VALUES = ["none", "sm", "md", "lg"];
 export const GRID_CELL_ASPECT_RATIO_VALUES = ["auto", "square"];
+export const GRID_MAX_WIDTH_VALUES = ["sm", "md", "lg"];
 // ─── Snap structural limits ───────────────────────────
 export const MAX_ELEMENTS = 64;
 export const MAX_ROOT_CHILDREN = 7;

package/dist/react/catalog-renderer.js

@@ -8,6 +8,7 @@ import { SnapImage } from "./components/image.js";
 import { SnapInput } from "./components/input.js";
 import { SnapItem } from "./components/item.js";
 import { SnapItemGroup } from "./components/item-group.js";
+import { SnapPaginator } from "./components/paginator.js";
 import { SnapProgress } from "./components/progress.js";
 import { SnapSeparator } from "./components/separator.js";
 import { SnapSlider } from "./components/slider.js";
@@ -29,6 +30,7 @@ export const SnapCatalogView = createRenderer(snapJsonRenderCatalog, {
     input: SnapInput,
     item: SnapItem,
     item_group: SnapItemGroup,
+    paginator: SnapPaginator,
     progress: SnapProgress,
     separator: SnapSeparator,
     slider: SnapSlider,

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

@@ -1,10 +1,12 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from "react";
+import { useStateStore } from "@json-render/react";
 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 { getPaginatorAction, runPaginatorAction, } from "../../ui/paginator-state.js";
 import { useSnapStackDirection } from "../stack-direction-context.js";
 import { ICON_MAP } from "./icon.js";
 function isExternalLinkAction(on) {
@@ -23,6 +25,8 @@ export function SnapActionButton({ element, emit, }) {
     const iconName = props.icon ? String(props.icon) : undefined;
     const colors = useSnapColors();
     const [hovered, setHovered] = useState(false);
+    const stateStore = useStateStore();
+    const paginatorAction = getPaginatorAction(element.on);
     const Icon = iconName ? ICON_MAP[iconName] : undefined;
     const showExternalIcon = isExternalLinkAction(element.on);
     const inHorizontalStack = useSnapStackDirection() === "horizontal";
@@ -50,5 +54,9 @@ export function SnapActionButton({ element, emit, }) {
      */
     _jsx("div", { className: inHorizontalStack
             ? "min-w-0 flex-auto"
-            : "w-full min-w-0", style: inHorizontalStack ? { flex: "1 1 auto" } : undefined, 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 } }))] }) }));
+            : "w-full min-w-0", style: inHorizontalStack ? { flex: "1 1 auto" } : undefined, children: _jsxs(Button, { type: "button", variant: isPrimary ? "default" : "secondary", className: cn("h-8 w-full gap-2 px-3 text-sm"), style: style, onClick: () => {
+                if (!runPaginatorAction(stateStore, paginatorAction)) {
+                    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

@@ -4,9 +4,12 @@ import { useStateStore } from "@json-render/react";
 import { cn } from "@neynar/ui/utils";
 import { POST_GRID_TAP_KEY, readableTextOnHex } from "@farcaster/snap";
 import { useSnapColors } from "../hooks/use-snap-colors.js";
+import { getPaginatorAction, runPaginatorAction, } from "../../ui/paginator-state.js";
 export function SnapCellGrid({ element: { props, on }, emit, }) {
-    const { get, set } = useStateStore();
+    const stateStore = useStateStore();
+    const { get, set } = stateStore;
     const colors = useSnapColors();
+    const paginatorAction = getPaginatorAction(on);
     const cols = Number(props.cols ?? 2);
     const rows = Number(props.rows ?? 2);
     const select = String(props.select ?? "off");
@@ -20,6 +23,13 @@ export function SnapCellGrid({ element: { props, on }, emit, }) {
     const gapPx = gapMap[gap] ?? 1;
     const rowHeight = typeof props.rowHeight === "number" ? props.rowHeight : 28;
     const squareCells = props.cellAspectRatio === "square";
+    const maxWidthKey = typeof props.maxWidth === "string" ? props.maxWidth : undefined;
+    const maxWidthMap = {
+        sm: 160,
+        md: 220,
+        lg: undefined,
+    };
+    const maxWidth = maxWidthKey ? maxWidthMap[maxWidthKey] : undefined;
     const name = props.name ? String(props.name) : POST_GRID_TAP_KEY;
     const tapPath = `/inputs/${name}`;
     const tapRaw = get(tapPath);
@@ -61,8 +71,10 @@ export function SnapCellGrid({ element: { props, on }, emit, }) {
         else {
             set(tapPath, wire);
         }
-        if (hasPressAction)
+        if (hasPressAction &&
+            !runPaginatorAction(stateStore, paginatorAction)) {
             emit("press");
+        }
     };
     /** Cells without a palette `color` — subtle fill so empty slots read as tiles. */
     const emptyCellBg = colors.mode === "dark"
@@ -101,6 +113,8 @@ export function SnapCellGrid({ element: { props, on }, emit, }) {
     return (_jsx("div", { style: {
             display: "grid",
             width: "100%",
+            maxWidth,
+            marginInline: maxWidth ? "auto" : undefined,
             gridTemplateColumns: `repeat(${cols}, 1fr)`,
             gap: gapPx,
             padding: 4,

package/dist/react/components/image.js

@@ -1,5 +1,5 @@
 "use client";
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { AspectRatio } from "@neynar/ui/aspect-ratio";
 import { cn } from "@neynar/ui/utils";
 import { useSnapStackDirection } from "../stack-direction-context.js";
@@ -12,8 +12,11 @@ function aspectToRatio(aspect) {
 export function SnapImage({ element: { props }, }) {
     const url = String(props.url ?? "");
     const alt = String(props.alt ?? "");
+    const title = props.title ? String(props.title) : "";
+    const subtitle = props.subtitle ? String(props.subtitle) : "";
+    const hasOverlay = title.length > 0 || subtitle.length > 0;
     const ratio = aspectToRatio(String(props.aspect ?? "1:1"));
     const stackDir = useSnapStackDirection();
     const inHorizontalStack = stackDir === "horizontal";
-    return (_jsx(AspectRatio, { ratio: ratio, className: cn("relative overflow-hidden rounded-lg", inHorizontalStack ? "min-w-0 flex-1 basis-0" : "w-full"), children: _jsx("img", { src: url, alt: alt, className: "absolute inset-0 size-full object-cover" }) }));
+    return (_jsxs(AspectRatio, { ratio: ratio, className: cn("relative overflow-hidden rounded-lg", inHorizontalStack ? "min-w-0 flex-1 basis-0" : "w-full"), children: [_jsx("img", { src: url, alt: alt, className: "absolute inset-0 size-full object-cover" }), hasOverlay && (_jsxs("div", { className: "absolute inset-x-0 bottom-0 bg-gradient-to-t from-black/75 via-black/35 to-transparent p-3 pt-8 text-white", children: [title && (_jsx("div", { className: "truncate text-sm font-semibold leading-5", children: title })), subtitle && (_jsx("div", { className: "truncate text-xs font-medium leading-4 text-white/85", children: subtitle }))] }))] }));
 }

package/dist/react/components/paginator.d.ts

@@ -0,0 +1,7 @@
+import { type ReactNode } from "react";
+export declare function SnapPaginator({ element: { props }, children, }: {
+    element: {
+        props: Record<string, unknown>;
+    };
+    children?: ReactNode;
+}): import("react/jsx-runtime").JSX.Element | null;

package/dist/react/components/paginator.js

@@ -0,0 +1,103 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Children, useEffect, useMemo, useState, } from "react";
+import { useStateStore } from "@json-render/react";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import { cn } from "@neynar/ui/utils";
+import { useSnapColors } from "../hooks/use-snap-colors.js";
+import { clampPaginatorPage, pageFromValue, SNAP_PAGINATOR_PAGE_COUNT_PATH, SNAP_PAGINATOR_PAGE_PATH, } from "../../ui/paginator-state.js";
+function clampInitialPage(value, pageCount) {
+    if (typeof value !== "number" || !Number.isInteger(value))
+        return 0;
+    return Math.min(Math.max(value, 0), Math.max(pageCount - 1, 0));
+}
+export function SnapPaginator({ element: { props }, children, }) {
+    const pages = useMemo(() => Children.toArray(children), [children]);
+    const colors = useSnapColors();
+    const { get, set } = useStateStore();
+    const initialPage = clampInitialPage(props.initialPage, pages.length);
+    const page = clampPaginatorPage(pageFromValue(get(SNAP_PAGINATOR_PAGE_PATH), initialPage), pages.length);
+    const activePage = Math.min(page, Math.max(pages.length - 1, 0));
+    const showControls = props.showControls !== false && pages.length > 1;
+    const showIndicators = props.showIndicators !== false && pages.length > 1;
+    const controlsPosition = props.controlsPosition === "top" ? "top" : "bottom";
+    const transition = props.transition === "fade" ||
+        props.transition === "scale" ||
+        props.transition === "none"
+        ? props.transition
+        : "slide";
+    const showControlBar = showControls || showIndicators;
+    const [transitionDirection, setTransitionDirection] = useState("next");
+    const canGoPrev = activePage > 0;
+    const canGoNext = activePage < pages.length - 1;
+    const goToPage = (targetPage) => {
+        const nextPage = clampPaginatorPage(targetPage, pages.length);
+        if (nextPage !== activePage) {
+            setTransitionDirection(nextPage > activePage ? "next" : "previous");
+        }
+        set(SNAP_PAGINATOR_PAGE_PATH, nextPage);
+    };
+    const goPrev = () => goToPage(activePage - 1);
+    const goNext = () => goToPage(activePage + 1);
+    useEffect(() => {
+        if (pages.length === 0)
+            return;
+        const nextPage = clampPaginatorPage(pageFromValue(get(SNAP_PAGINATOR_PAGE_PATH), initialPage), pages.length);
+        if (get(SNAP_PAGINATOR_PAGE_PATH) !== nextPage) {
+            set(SNAP_PAGINATOR_PAGE_PATH, nextPage);
+        }
+        if (get(SNAP_PAGINATOR_PAGE_COUNT_PATH) !== pages.length) {
+            set(SNAP_PAGINATOR_PAGE_COUNT_PATH, pages.length);
+        }
+    }, [get, initialPage, pages.length, set]);
+    if (pages.length === 0)
+        return null;
+    const pageAnimation = transition === "none"
+        ? undefined
+        : transition === "fade"
+            ? "snapPaginatorFade 180ms ease-out"
+            : transition === "scale"
+                ? "snapPaginatorScale 240ms cubic-bezier(0.16, 1, 0.3, 1)"
+                : "snapPaginatorSlide 260ms cubic-bezier(0.16, 1, 0.3, 1)";
+    const controlBar = showControlBar ? (_jsxs("div", { className: "flex min-h-7 w-full items-center justify-between gap-2", children: [showControls ? (_jsx("button", { type: "button", "aria-label": "Previous page", disabled: !canGoPrev, onClick: goPrev, className: cn("inline-flex size-7 items-center justify-center rounded-md border text-sm transition-opacity", canGoPrev ? "cursor-pointer opacity-100" : "cursor-default opacity-35"), style: {
+                    borderColor: colors.border,
+                    backgroundColor: colors.muted,
+                    color: colors.text,
+                }, children: _jsx(ChevronLeft, { size: 15 }) })) : (_jsx("span", {})), showIndicators ? (_jsx("div", { className: "flex flex-1 items-center justify-center gap-1.5", children: pages.map((_, index) => {
+                    const current = index === activePage;
+                    return (_jsx("span", { "aria-label": `Page ${index + 1}${current ? ", current" : ""}`, className: cn("block rounded-full", current ? "size-2.5" : "size-2"), style: {
+                            backgroundColor: current
+                                ? colors.accent
+                                : colors.mode === "dark"
+                                    ? "rgba(255,255,255,0.5)"
+                                    : "rgba(0,0,0,0.28)",
+                            boxShadow: current
+                                ? `0 0 0 2px ${colors.mode === "dark" ? "rgba(255,255,255,0.18)" : "rgba(0,0,0,0.12)"}`
+                                : undefined,
+                        } }, index));
+                }) })) : (_jsx("span", { className: "flex-1" })), showControls ? (_jsx("button", { type: "button", "aria-label": "Next page", disabled: !canGoNext, onClick: goNext, className: cn("inline-flex size-7 items-center justify-center rounded-md border text-sm transition-opacity", canGoNext ? "cursor-pointer opacity-100" : "cursor-default opacity-35"), style: {
+                    borderColor: colors.border,
+                    backgroundColor: colors.muted,
+                    color: colors.text,
+                }, children: _jsx(ChevronRight, { size: 15 }) })) : (_jsx("span", {}))] })) : null;
+    return (_jsxs("div", { className: "flex w-full min-w-0 flex-col gap-2", children: [controlsPosition === "top" ? controlBar : null, _jsx("div", { "data-snap-paginator-page": true, className: "w-full min-w-0", style: {
+                    "--snap-paginator-x": transitionDirection === "previous" ? "-22px" : "22px",
+                    animation: pageAnimation,
+                }, children: pages[activePage] }, activePage), controlsPosition === "bottom" ? controlBar : null, _jsx("style", { children: `
+        @keyframes snapPaginatorSlide {
+          from { opacity: 0.35; transform: translateX(var(--snap-paginator-x, 22px)) scale(0.985); }
+          to { opacity: 1; transform: translateX(0) scale(1); }
+        }
+        @keyframes snapPaginatorFade {
+          from { opacity: 0.2; }
+          to { opacity: 1; }
+        }
+        @keyframes snapPaginatorScale {
+          from { opacity: 0.25; transform: scale(0.94); }
+          to { opacity: 1; transform: scale(1); }
+        }
+        @media (prefers-reduced-motion: reduce) {
+          [data-snap-paginator-page] { animation: none !important; }
+        }
+      ` })] }));
+}

package/dist/react/components/stack.js

@@ -4,16 +4,16 @@ import { cn } from "@neynar/ui/utils";
 import { childrenShouldUseHorizontalButtonLayout, childrenAreAllButtons, countRenderableChildren, defaultHorizontalGapSize, } from "../../stack-horizontal-utils.js";
 import { SnapStackDirectionProvider, useSnapStackDirection, } from "../stack-direction-context.js";
 const VGAP = {
-    none: "gap-0",
-    sm: "gap-1",
-    md: "gap-4",
-    lg: "gap-6",
+    none: 0,
+    sm: 4,
+    md: 16,
+    lg: 24,
 };
 const HGAP = {
-    none: "gap-0",
-    sm: "gap-1",
-    md: "gap-2",
-    lg: "gap-4",
+    none: 0,
+    sm: 4,
+    md: 8,
+    lg: 16,
 };
 const JUSTIFY_FLEX = {
     start: "justify-start",
@@ -71,7 +71,7 @@ export function SnapStack({ element: { props }, children, }) {
             : isHorizontal
                 ? defaultHorizontalGapSize(horizontalChildCount)
                 : "md";
-    const gap = isHorizontal
+    const gapPx = isHorizontal
         ? (HGAP[gapKey] ?? HGAP.md)
         : (VGAP[gapKey] ?? VGAP.md);
     const columnGridClass = explicitEqualWidth && equalWidthColumnCount !== undefined
@@ -90,15 +90,18 @@ export function SnapStack({ element: { props }, children, }) {
         (!isHorizontal || !explicitEqualWidth);
     /** Single flex row (nowrap): peers stay side-by-side and shrink via min-w-0 / flex-1 on nested stacks. */
     const horizontalFlexClasses = "flex min-w-0 flex-row flex-nowrap items-stretch [&>*]:min-w-0";
-    const equalWidthStyle = explicitEqualWidth && equalWidthColumnCount !== undefined
-        ? {
-            display: "grid",
-            gridTemplateColumns: `repeat(${equalWidthColumnCount}, minmax(0, 1fr))`,
-        }
-        : undefined;
+    const layoutStyle = {
+        gap: gapPx,
+        ...(explicitEqualWidth && equalWidthColumnCount !== undefined
+            ? {
+                display: "grid",
+                gridTemplateColumns: `repeat(${equalWidthColumnCount}, minmax(0, 1fr))`,
+            }
+            : {}),
+    };
     return (_jsx(SnapStackDirectionProvider, { direction: isHorizontal ? "horizontal" : "vertical", children: _jsx("div", { className: cn(rootWidthClass, isHorizontal
                 ? explicitEqualWidth && columnGridClass
-                    ? cn(columnGridClass, gap)
-                    : cn(horizontalFlexClasses, gap, justifyBlockGrid ? justifyFlex : undefined)
-                : cn("flex min-w-0 w-full flex-col", gap, justifyFlex)), style: equalWidthStyle, children: children }) }));
+                    ? columnGridClass
+                    : cn(horizontalFlexClasses, justifyBlockGrid ? justifyFlex : undefined)
+                : cn("flex min-w-0 w-full flex-col", justifyFlex)), style: layoutStyle, children: children }) }));
 }

package/dist/react/components/text.js

@@ -4,6 +4,7 @@ import { Text } from "@neynar/ui/typography";
 import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors.js";
 import { useSnapStackDirection } from "../stack-direction-context.js";
+import { useSnapVersion } from "../snap-version-context.js";
 const SIZE_MAP = {
     md: { textSize: "base" },
     sm: { textSize: "sm" },
@@ -16,7 +17,13 @@ export function SnapText({ element: { props }, }) {
     const config = SIZE_MAP[size] ?? SIZE_MAP.md;
     const colors = useSnapColors();
     const stackDir = useSnapStackDirection();
+    const snapVersion = useSnapVersion();
     const inHorizontalStack = stackDir === "horizontal";
+    const maxLines = typeof props.maxLines === "number"
+        ? props.maxLines
+        : snapVersion === "2.0"
+            ? 1
+            : undefined;
     return (_jsx(Text, { size: config.textSize, weight: weight, align: align, className: cn(
         /**
          * Row peers hug content like RN `wrapRow` — `min-w-0 shrink` lets text wrap
@@ -26,5 +33,16 @@ export function SnapText({ element: { props }, }) {
          * column's height, distributing siblings when the row is taller than its
          * content (e.g. text next to a tall image).
          */
-        inHorizontalStack ? "min-w-0 shrink" : "min-w-0"), style: { color: colors.text }, children: content }));
+        inHorizontalStack ? "min-w-0 shrink" : "min-w-0"), style: {
+            color: colors.text,
+            lineHeight: size === "sm" ? 1.35 : 1.4,
+            ...(maxLines
+                ? {
+                    display: "-webkit-box",
+                    WebkitBoxOrient: "vertical",
+                    WebkitLineClamp: maxLines,
+                    overflow: "hidden",
+                }
+                : {}),
+        }, children: content }));
 }

package/dist/react/snap-version-context.d.ts

@@ -0,0 +1,3 @@
+import type { SpecVersion } from "../constants.js";
+export declare const SnapVersionProvider: import("react").Provider<"1.0" | "2.0">;
+export declare function useSnapVersion(): SpecVersion;

package/dist/react/snap-version-context.js

@@ -0,0 +1,7 @@
+"use client";
+import { createContext, useContext } from "react";
+const SnapVersionContext = createContext("1.0");
+export const SnapVersionProvider = SnapVersionContext.Provider;
+export function useSnapVersion() {
+    return useContext(SnapVersionContext);
+}

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

@@ -3,7 +3,7 @@ import type { SnapActionHandlers, SnapPage } from "./index.js";
 export declare function applyStatePaths(model: Record<string, unknown>, changes: {
     path: string;
     value: unknown;
-}[] | Record<string, unknown>): void;
+}[] | Record<string, unknown> | null | undefined): void;
 export declare function SnapLoadingOverlay({ appearance, accentHex, active, }: {
     appearance: "light" | "dark";
     accentHex: string;

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

@@ -3,11 +3,14 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { snapJsonRenderCatalog } from "../ui/index.js";
 import { SnapCatalogView } from "./catalog-renderer.js";
 import { SnapPreviewAccentProvider } from "./accent-context.js";
+import { SnapVersionProvider } from "./snap-version-context.js";
 import { resolveSnapPaletteHex } from "./lib/resolve-palette-hex.js";
 import { snapPreviewPrimaryCssProperties } from "./lib/preview-primary-css.js";
 import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
 // ─── Internal helpers ──────────────────────────────────
 export function applyStatePaths(model, changes) {
+    if (!changes)
+        return;
     const entries = Array.isArray(changes)
         ? changes.map((c) => [c.path, c.value])
         : Object.entries(changes);
@@ -38,6 +41,26 @@ export function applyStatePaths(model, changes) {
         }
     }
 }
+function withDefaultElementProps(spec) {
+    if (!spec || typeof spec !== "object" || !("elements" in spec))
+        return spec;
+    const elements = spec.elements;
+    if (!elements || typeof elements !== "object")
+        return spec;
+    let changed = false;
+    const nextElements = {};
+    for (const [id, element] of Object.entries(elements)) {
+        if (element.props !== undefined) {
+            nextElements[id] = element;
+            continue;
+        }
+        changed = true;
+        nextElements[id] = { ...element, props: {} };
+    }
+    return changed
+        ? { ...spec, elements: nextElements }
+        : spec;
+}
 const CONFETTI_COLORS = [
     "#907AA9",
     "#EC4899",
@@ -217,7 +240,7 @@ const PALETTE = [
 // ─── SnapViewCore ────────────────────────────────────
 // Shared rendering logic used by both v1 and v2.
 export function SnapViewCore({ snap, handlers, loading = false, appearance = "dark", loadingOverlay, }) {
-    const spec = snap.ui;
+    const spec = useMemo(() => withDefaultElementProps(snap.ui), [snap.ui]);
     const initialState = useMemo(() => spec.state ?? { inputs: {} }, [spec]);
     const stateRef = useRef(initialState);
     useEffect(() => {
@@ -316,7 +339,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), 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) }) })] }));
+    return (_jsxs("div", { style: { position: "relative", width: "100%" }, children: [showConfetti && _jsx(ConfettiOverlay, {}, confettiKey), showFireworks && _jsx(FireworksOverlay, {}, fireworksKey), loadingOverlay === undefined ? (_jsx(SnapLoadingOverlay, { appearance: appearance, accentHex: accentHex, active: loading })) : loading ? (_jsx(_Fragment, { children: loadingOverlay })) : null, _jsx("div", { style: previewSurfaceStyle, children: _jsx(SnapPreviewAccentProvider, { pageAccent: snap.theme?.accent, appearance: appearance, children: _jsx(SnapVersionProvider, { value: snap.version === "2.0" ? "2.0" : "1.0", children: _jsx(SnapCatalogView, { spec: spec, state: initialState, loading: false, onStateChange: (changes) => {
+                                applyStatePaths(stateRef.current, changes);
+                            }, onAction: handleAction }, pageKey) }) }) })] }));
 }

package/dist/react-native/catalog-renderer.js

@@ -7,6 +7,7 @@ import { SnapImage } from "./components/snap-image.js";
 import { SnapInput } from "./components/snap-input.js";
 import { SnapItem } from "./components/snap-item.js";
 import { SnapItemGroup } from "./components/snap-item-group.js";
+import { SnapPaginator } from "./components/snap-paginator.js";
 import { SnapProgress } from "./components/snap-progress.js";
 import { SnapSeparator } from "./components/snap-separator.js";
 import { SnapSlider } from "./components/snap-slider.js";
@@ -28,6 +29,7 @@ export const SnapCatalogView = createRenderer(snapJsonRenderCatalog, {
     input: SnapInput,
     item: SnapItem,
     item_group: SnapItemGroup,
+    paginator: SnapPaginator,
     progress: SnapProgress,
     separator: SnapSeparator,
     slider: SnapSlider,

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

@@ -1,8 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useStateStore } from "@json-render/react-native";
 import { Pressable, StyleSheet, Text, View } from "react-native";
 import { ExternalLink } from "lucide-react-native";
 import { useSnapPalette } from "../use-snap-palette.js";
 import { useSnapTheme } from "../theme.js";
+import { getPaginatorAction, runPaginatorAction, } from "../../ui/paginator-state.js";
 import { useSnapStackDirection } from "../stack-direction-context.js";
 import { ICON_MAP } from "./snap-icon.js";
 function isExternalLinkAction(on) {
@@ -26,6 +28,8 @@ export function SnapActionButton({ element, emit, }) {
     const inHorizontalStack = useSnapStackDirection() === "horizontal";
     const on = element.on;
     const showExternalIcon = isExternalLinkAction(on);
+    const stateStore = useStateStore();
+    const paginatorAction = getPaginatorAction(on);
     return (_jsx(View, { style: inHorizontalStack ? styles.outerHorizontal : styles.outer, children: _jsxs(Pressable, { style: ({ pressed }) => [
                 styles.btn,
                 isPrimary ? styles.btnDefault : styles.btnOther,
@@ -34,6 +38,8 @@ export function SnapActionButton({ element, emit, }) {
                     : { backgroundColor: pressed ? colors.mutedHover : colors.muted },
                 pressed && styles.pressed,
             ], onPress: () => {
+                if (runPaginatorAction(stateStore, paginatorAction))
+                    return;
                 void (async () => {
                     try {
                         await emit("press");
@@ -73,10 +79,10 @@ const styles = StyleSheet.create({
         gap: 8,
     },
     btnDefault: {
-        paddingVertical: 10,
+        paddingVertical: 8,
     },
     btnOther: {
-        paddingVertical: 8,
+        paddingVertical: 6,
     },
     pressed: { opacity: 0.88 },
 });

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

@@ -4,17 +4,27 @@ import { useStateStore } from "@json-render/react-native";
 import { useSnapPalette } from "../use-snap-palette.js";
 import { useSnapTheme } from "../theme.js";
 import { POST_GRID_TAP_KEY, readableTextOnHex } from "@farcaster/snap";
+import { getPaginatorAction, runPaginatorAction, } from "../../ui/paginator-state.js";
 export function SnapCellGrid({ element, emit, }) {
     const { props } = element;
     const on = element.on;
     const { hex, appearance } = useSnapPalette();
     const { colors } = useSnapTheme();
-    const { get, set } = useStateStore();
+    const stateStore = useStateStore();
+    const { get, set } = stateStore;
+    const paginatorAction = getPaginatorAction(on);
     const cols = Number(props.cols ?? 2);
     const rows = Number(props.rows ?? 2);
     const cells = Array.isArray(props.cells) ? props.cells : [];
     const rowHeight = typeof props.rowHeight === "number" ? props.rowHeight : 28;
     const squareCells = props.cellAspectRatio === "square";
+    const maxWidthKey = typeof props.maxWidth === "string" ? props.maxWidth : undefined;
+    const maxWidthMap = {
+        sm: 160,
+        md: 220,
+        lg: undefined,
+    };
+    const maxWidth = maxWidthKey ? maxWidthMap[maxWidthKey] : undefined;
     const gap = String(props.gap ?? "sm");
     const gapMap = { none: 0, sm: 1, md: 2, lg: 4 };
     const gapPx = gapMap[gap] ?? 1;
@@ -64,8 +74,10 @@ export function SnapCellGrid({ element, emit, }) {
         else {
             set(tapPath, wire);
         }
-        if (hasPressAction)
+        if (hasPressAction &&
+            !runPaginatorAction(stateStore, paginatorAction)) {
             emit("press");
+        }
     };
     const ringOuter = appearance === "dark" ? "#fff" : "#000";
     const ringInner = appearance === "dark" ? "#000" : "#fff";
@@ -110,6 +122,8 @@ export function SnapCellGrid({ element, emit, }) {
     return (_jsx(View, { style: [
             styles.wrap,
             {
+                maxWidth,
+                alignSelf: maxWidth ? "center" : undefined,
                 gap: gapPx,
                 backgroundColor: colors.muted,
                 padding: 4,

package/dist/react-native/components/snap-image.js

@@ -1,6 +1,6 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Image } from "expo-image";
-import { StyleSheet, View } from "react-native";
+import { StyleSheet, Text, View } from "react-native";
 import { useSnapStackDirection } from "../stack-direction-context.js";
 function aspectToRatio(aspect) {
     const [w, h] = aspect.split(":").map(Number);
@@ -11,14 +11,17 @@ function aspectToRatio(aspect) {
 export function SnapImage({ element: { props }, }) {
     const url = String(props.url ?? "");
     const alt = String(props.alt ?? "");
+    const title = props.title ? String(props.title) : "";
+    const subtitle = props.subtitle ? String(props.subtitle) : "";
+    const hasOverlay = title.length > 0 || subtitle.length > 0;
     const ratio = aspectToRatio(String(props.aspect ?? "1:1"));
     const stackDir = useSnapStackDirection();
     const inHorizontalStack = stackDir === "horizontal";
-    return (_jsx(View, { style: [
+    return (_jsxs(View, { style: [
             styles.frame,
             inHorizontalStack ? styles.frameInHorizontalRow : styles.frameFullWidth,
             { aspectRatio: ratio },
-        ], children: _jsx(Image, { source: { uri: url }, style: StyleSheet.absoluteFill, contentFit: "cover", accessibilityLabel: alt || undefined }) }));
+        ], children: [_jsx(Image, { source: { uri: url }, style: StyleSheet.absoluteFill, contentFit: "cover", accessibilityLabel: alt || undefined }), hasOverlay ? (_jsxs(View, { style: styles.overlay, children: [title ? (_jsx(Text, { numberOfLines: 1, style: styles.title, children: title })) : null, subtitle ? (_jsx(Text, { numberOfLines: 1, style: styles.subtitle, children: subtitle })) : null] })) : null] }));
 }
 const styles = StyleSheet.create({
     frame: {
@@ -33,4 +36,26 @@ const styles = StyleSheet.create({
         flex: 1,
         minWidth: 0,
     },
+    overlay: {
+        position: "absolute",
+        left: 0,
+        right: 0,
+        bottom: 0,
+        paddingHorizontal: 12,
+        paddingTop: 24,
+        paddingBottom: 10,
+        backgroundColor: "rgba(0, 0, 0, 0.48)",
+    },
+    title: {
+        color: "#fff",
+        fontSize: 14,
+        lineHeight: 18,
+        fontWeight: "700",
+    },
+    subtitle: {
+        color: "rgba(255, 255, 255, 0.85)",
+        fontSize: 12,
+        lineHeight: 16,
+        fontWeight: "500",
+    },
 });

package/dist/react-native/components/snap-paginator.d.ts

@@ -0,0 +1,5 @@
+import type { ComponentRenderProps } from "@json-render/react-native";
+import { type ReactNode } from "react";
+export declare function SnapPaginator({ element: { props }, children, }: ComponentRenderProps<Record<string, unknown>> & {
+    children?: ReactNode;
+}): import("react").JSX.Element;