@farcaster/snap 2.5.1 → 2.6.1

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

@@ -4,8 +4,8 @@ import { Platform, Pressable, StyleSheet, Text, View } from "react-native";
 import { SnapThemeProvider, useSnapTheme } from "../theme.js";
 import { SnapLoadingOverlay, SnapViewCoreInner, resolveAccentHex, } from "../snap-view-core.js";
 import { validateSnapResponse, } from "@farcaster/snap";
+import { getSnapExpansionState, SNAP_MAX_HEIGHT } from "../expand-state.js";
 // ─── Constants ───────────────────────────────────────
-const SNAP_MAX_HEIGHT = 500;
 const SNAP_WARNING_HEIGHT = 700;
 const SHOW_MORE_OVERHANG = 14;
 // ─── Validation fallback ─────────────────────────────
@@ -51,7 +51,7 @@ export function SnapViewV2({ snap, handlers, loading = false, appearance = "dark
     return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapViewV2Inner, { snap: snap, handlers: handlers, loading: loading, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, loadingOverlay: loadingOverlay }) }));
 }
 // ─── SnapCardV2 (card frame + height limits) ─────────
-function SnapCardV2Inner({ snap, handlers, loading, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, appearance, plain, loadingOverlay, }) {
+function SnapCardV2Inner({ snap, handlers, loading, borderRadius, showOverflowWarning, onValidationError, validationErrorFallback, actionError, appearance, plain, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, }) {
     const { colors, mode } = useSnapTheme();
     const accentHex = resolveAccentHex(snap.theme?.accent, mode);
     const [contentHeight, setContentHeight] = useState(0);
@@ -60,13 +60,22 @@ function SnapCardV2Inner({ snap, handlers, loading, borderRadius, showOverflowWa
         setIsExpanded(false);
         setContentHeight(0);
     }, [snap]);
-    const isExpandable = !showOverflowWarning && contentHeight > SNAP_MAX_HEIGHT + 1;
-    const isClipped = isExpandable && !isExpanded;
+    const expansion = getSnapExpansionState({
+        contentHeight,
+        internalExpanded: isExpanded,
+        forceExpanded,
+        onExpandPress,
+        expandButtonLabel,
+        showOverflowWarning,
+    });
+    const expandButtonInsideCard = typeof onExpandPress === "function";
     const content = (_jsx(SnapViewV2Inner, { snap: snap, handlers: handlers, loading: loading, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, loadingOverlay: null }));
     if (plain) {
-        return (_jsxs(_Fragment, { children: [_jsx(View, { style: isClipped ? { maxHeight: SNAP_MAX_HEIGHT, overflow: "hidden" } : undefined, children: _jsx(View, { collapsable: false, onLayout: (e) => {
+        return (_jsxs(_Fragment, { children: [_jsx(View, { style: expansion.clipped
+                        ? { maxHeight: expansion.maxHeight, overflow: "hidden" }
+                        : undefined, children: _jsx(View, { collapsable: false, onLayout: (e) => {
                             const nextHeight = Math.round(e.nativeEvent.layout.height);
-                            setContentHeight((current) => isClipped
+                            setContentHeight((current) => expansion.clipped
                                 ? Math.max(current, nextHeight)
                                 : current === nextHeight
                                     ? current
@@ -75,43 +84,65 @@ function SnapCardV2Inner({ snap, handlers, loading, borderRadius, showOverflowWa
                     ? loadingOverlay === undefined
                         ? _jsx(SnapLoadingOverlay, { appearance: mode, accentHex: accentHex })
                         : loadingOverlay
-                    : null, isExpandable ? (_jsx(View, { style: [cardStyles.expandRow, cardStyles.expandRowPlain], children: _jsx(Pressable, { style: ({ pressed }) => [
+                    : null, expansion.showButton ? (_jsx(View, { style: [cardStyles.expandRow, cardStyles.expandRowPlain], children: _jsx(Pressable, { style: ({ pressed }) => [
                             cardStyles.expandButton,
                             {
                                 backgroundColor: pressed ? colors.mutedHover : colors.muted,
                             },
-                        ], onPress: () => setIsExpanded((value) => !value), children: _jsx(Text, { style: [cardStyles.expandButtonText, { color: colors.text }], children: isExpanded ? "Show less" : "Show more" }) }) })) : null] }));
+                        ], onPress: () => {
+                            if (expansion.useInternalToggle) {
+                                setIsExpanded((value) => !value);
+                            }
+                            else {
+                                onExpandPress?.();
+                            }
+                        }, children: _jsx(Text, { style: [cardStyles.expandButtonText, { color: colors.text }], children: expansion.buttonLabel }) }) })) : null] }));
     }
-    const overflowAmount = showOverflowWarning ? contentHeight - SNAP_MAX_HEIGHT : 0;
+    const overflowAmount = expansion.showOverflowWarning
+        ? contentHeight - SNAP_MAX_HEIGHT
+        : 0;
     const isDark = mode === "dark";
     const pillBg = isDark ? "rgba(40,40,40,0.92)" : "rgba(255,255,255,0.92)";
     const pillBgPressed = isDark ? "rgba(60,60,60,0.95)" : "rgba(240,240,240,0.95)";
-    return (_jsxs(View, { style: { paddingBottom: isExpandable ? SHOW_MORE_OVERHANG : 0 }, children: [_jsxs(View, { style: { position: "relative" }, children: [_jsxs(View, { style: {
+    return (_jsxs(View, { style: {
+            paddingBottom: expansion.showButton && !expandButtonInsideCard ? SHOW_MORE_OVERHANG : 0,
+        }, children: [_jsxs(View, { style: { position: "relative" }, children: [_jsxs(View, { style: {
                             borderRadius,
                             borderWidth: 1,
                             borderColor: colors.border,
                             backgroundColor: colors.surface,
-                            maxHeight: showOverflowWarning ? undefined : isClipped ? SNAP_MAX_HEIGHT : undefined,
+                            maxHeight: expansion.showOverflowWarning
+                                ? undefined
+                                : expansion.maxHeight,
                             overflow: "hidden",
                             minHeight: 120,
                         }, children: [_jsx(View, { collapsable: false, onLayout: (e) => {
                                     const nextHeight = Math.round(e.nativeEvent.layout.height);
-                                    setContentHeight((current) => isClipped
+                                    setContentHeight((current) => expansion.clipped
                                         ? Math.max(current, nextHeight)
                                         : current === nextHeight
                                             ? current
                                             : nextHeight);
-                                }, style: { paddingHorizontal: 16, paddingVertical: 16 }, children: content }), showOverflowWarning && contentHeight > SNAP_MAX_HEIGHT && (_jsxs(View, { style: { position: "absolute", top: SNAP_MAX_HEIGHT, left: 0, right: 0, height: overflowAmount, zIndex: 10, pointerEvents: "none" }, children: [_jsx(View, { style: { height: 1, borderTopWidth: 1, borderStyle: "dashed", borderColor: "rgba(255,100,100,0.6)" } }), _jsx(View, { style: { position: "absolute", top: -10, right: 4, backgroundColor: "rgba(0,0,0,0.7)", paddingHorizontal: 4, paddingVertical: 1, borderRadius: 3 }, children: _jsxs(Text, { style: { fontSize: 10, color: "rgba(255,100,100,0.7)", fontFamily: Platform.select({ ios: "Menlo", default: "monospace" }) }, children: [SNAP_MAX_HEIGHT, "px"] }) }), _jsx(View, { style: { flex: 1, backgroundColor: "rgba(255,50,50,0.15)" } })] })), loading
+                                }, style: { paddingHorizontal: 16, paddingVertical: 16 }, children: content }), expansion.showOverflowWarning && contentHeight > SNAP_MAX_HEIGHT && (_jsxs(View, { style: { position: "absolute", top: SNAP_MAX_HEIGHT, left: 0, right: 0, height: overflowAmount, zIndex: 10, pointerEvents: "none" }, children: [_jsx(View, { style: { height: 1, borderTopWidth: 1, borderStyle: "dashed", borderColor: "rgba(255,100,100,0.6)" } }), _jsx(View, { style: { position: "absolute", top: -10, right: 4, backgroundColor: "rgba(0,0,0,0.7)", paddingHorizontal: 4, paddingVertical: 1, borderRadius: 3 }, children: _jsxs(Text, { style: { fontSize: 10, color: "rgba(255,100,100,0.7)", fontFamily: Platform.select({ ios: "Menlo", default: "monospace" }) }, children: [SNAP_MAX_HEIGHT, "px"] }) }), _jsx(View, { style: { flex: 1, backgroundColor: "rgba(255,50,50,0.15)" } })] })), loading
                                 ? loadingOverlay === undefined
                                     ? _jsx(SnapLoadingOverlay, { appearance: mode, accentHex: accentHex })
                                     : loadingOverlay
-                                : null] }), isExpandable ? (_jsx(View, { pointerEvents: "box-none", style: cardStyles.expandFloat, children: _jsx(Pressable, { style: ({ pressed }) => [
+                                : null] }), expansion.showButton ? (_jsx(View, { pointerEvents: "box-none", style: expandButtonInsideCard
+                            ? cardStyles.expandFloatInset
+                            : cardStyles.expandFloat, children: _jsx(Pressable, { style: ({ pressed }) => [
                                 cardStyles.expandButton,
                                 {
                                     backgroundColor: pressed ? pillBgPressed : pillBg,
                                     borderColor: colors.border,
                                 },
-                            ], onPress: () => setIsExpanded((value) => !value), children: _jsx(Text, { style: [cardStyles.expandButtonText, { color: colors.text }], children: isExpanded ? "Show less" : "Show more" }) }) })) : null] }), actionError && (_jsx(Text, { style: {
+                            ], onPress: () => {
+                                if (expansion.useInternalToggle) {
+                                    setIsExpanded((value) => !value);
+                                }
+                                else {
+                                    onExpandPress?.();
+                                }
+                            }, children: _jsx(Text, { style: [cardStyles.expandButtonText, { color: colors.text }], children: expansion.buttonLabel }) }) })) : null] }), actionError && (_jsx(Text, { style: {
                     paddingHorizontal: 12,
                     paddingVertical: 8,
                     fontSize: 13,
@@ -120,8 +151,8 @@ function SnapCardV2Inner({ snap, handlers, loading, borderRadius, showOverflowWa
                         : "rgba(200,0,0,0.8)",
                 }, children: actionError }))] }));
 }
-export function SnapCardV2({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, loadingOverlay, }) {
-    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapCardV2Inner, { snap: snap, handlers: handlers, loading: loading, borderRadius: borderRadius, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, appearance: appearance, plain: plain, loadingOverlay: loadingOverlay }) }));
+export function SnapCardV2({ snap, handlers, loading = false, appearance = "dark", colors, borderRadius = 16, showOverflowWarning = false, onValidationError, validationErrorFallback, actionError, plain = false, loadingOverlay, forceExpanded, expandButtonLabel, onExpandPress, }) {
+    return (_jsx(SnapThemeProvider, { appearance: appearance, colors: colors, children: _jsx(SnapCardV2Inner, { snap: snap, handlers: handlers, loading: loading, borderRadius: borderRadius, showOverflowWarning: showOverflowWarning, onValidationError: onValidationError, validationErrorFallback: validationErrorFallback, actionError: actionError, appearance: appearance, plain: plain, loadingOverlay: loadingOverlay, forceExpanded: forceExpanded, expandButtonLabel: expandButtonLabel, onExpandPress: onExpandPress }) }));
 }
 const cardStyles = StyleSheet.create({
     frameRing: { alignSelf: "stretch" },
@@ -137,6 +168,18 @@ const cardStyles = StyleSheet.create({
         alignItems: "center",
         justifyContent: "center",
     },
+    expandFloatInset: {
+        position: "absolute",
+        left: 0,
+        right: 0,
+        bottom: 10,
+        height: 28,
+        alignItems: "center",
+        justifyContent: "center",
+    },
+    expandRow: {
+        alignItems: "center",
+    },
     expandRowPlain: {
         paddingTop: 8,
         alignItems: "center",

package/dist/ui/catalog.d.ts

@@ -319,8 +319,29 @@ export declare const snapJsonRenderCatalog: import("@json-render/core").Catalog<
                     "16:9": "16:9";
                     "4:3": "4:3";
                     "9:16": "9:16";
+                    "4:1": "4:1";
                 }>;
                 alt: z.ZodOptional<z.ZodString>;
+                title: z.ZodOptional<z.ZodString>;
+                subtitle: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+            description: string;
+        };
+        paginator: {
+            props: z.ZodObject<{
+                initialPage: z.ZodOptional<z.ZodNumber>;
+                showIndicators: z.ZodOptional<z.ZodBoolean>;
+                showControls: z.ZodOptional<z.ZodBoolean>;
+                controlsPosition: z.ZodOptional<z.ZodEnum<{
+                    top: "top";
+                    bottom: "bottom";
+                }>>;
+                transition: z.ZodOptional<z.ZodEnum<{
+                    none: "none";
+                    slide: "slide";
+                    fade: "fade";
+                    scale: "scale";
+                }>>;
             }, z.core.$strip>;
             description: string;
         };
@@ -393,6 +414,7 @@ export declare const snapJsonRenderCatalog: import("@json-render/core").Catalog<
                     left: "left";
                     right: "right";
                 }>>;
+                maxLines: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>;
             description: string;
         };
@@ -469,6 +491,11 @@ export declare const snapJsonRenderCatalog: import("@json-render/core").Catalog<
                     square: "square";
                 }>>;
                 rowHeight: z.ZodOptional<z.ZodNumber>;
+                maxWidth: z.ZodOptional<z.ZodEnum<{
+                    sm: "sm";
+                    md: "md";
+                    lg: "lg";
+                }>>;
                 select: z.ZodOptional<z.ZodEnum<{
                     multiple: "multiple";
                     off: "off";
@@ -545,5 +572,23 @@ export declare const snapJsonRenderCatalog: import("@json-render/core").Catalog<
                 buyToken: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>;
         };
+        paginator_next: {
+            description: string;
+            params: z.ZodObject<{
+                page: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>;
+        };
+        paginator_prev: {
+            description: string;
+            params: z.ZodObject<{
+                page: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>;
+        };
+        paginator_go_to: {
+            description: string;
+            params: z.ZodObject<{
+                page: z.ZodNumber;
+            }, z.core.$strip>;
+        };
     };
 }>;

package/dist/ui/catalog.js

@@ -10,6 +10,7 @@ import { inputProps } from "./input.js";
 import { itemProps } from "./item.js";
 import { itemGroupProps } from "./item-group.js";
 import { imageProps } from "./image.js";
+import { paginatorProps } from "./paginator.js";
 import { progressProps } from "./progress.js";
 import { separatorProps } from "./separator.js";
 import { sliderProps } from "./slider.js";
@@ -62,7 +63,11 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
         },
         image: {
             props: imageProps,
-            description: "HTTPS image with fixed aspect ratio.",
+            description: "HTTPS image with fixed aspect ratio. Supports compact 4:1 banners and optional title/subtitle overlay text.",
+        },
+        paginator: {
+            props: paginatorProps,
+            description: "Client-side paginator. Children are page element ids; the @farcaster/snap React/React Native components render one page at a time with optional built-in previous/next controls and indicators, optional top/bottom controlsPosition, and author-controlled local transition (slide | fade | scale | none). Buttons or cell_grid cells in the same snap can bind paginator_next, paginator_prev, or paginator_go_to for custom local navigation. Only one paginator is supported per rendered snap in this release. Page index is json-render local UI state and is not posted as input.",
         },
         progress: {
             props: progressProps,
@@ -82,7 +87,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
         },
         text: {
             props: textProps,
-            description: "Text block — size: md (body, default), sm (caption). Optional weight and align.",
+            description: "Text block — size: md (body, default), sm (caption). Optional weight, align, and maxLines. Text does not clamp by default; set maxLines to bound rendered lines.",
         },
         bar_chart: {
             props: barChartProps,
@@ -90,7 +95,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
         },
         cell_grid: {
             props: cellGridProps,
-            description: "Cell grid — sparse colored cells on a rows×cols grid. Cell color and textColor are palette names or literal #rrggbb hex values (hex ignores page accent); textColor overrides the default auto-contrast text color. Two interaction modes: leave select 'off' and bind on.press to fire an action per cell press (inputs[name] is the pressed 'row,col' before the action runs); or set select 'single'/'multiple' for press-to-select with a visual ring (no auto-fire — pair with a separate submit button). on.press is ignored when select is on.",
+            description: "Cell grid — sparse colored cells on a rows×cols grid. Set maxWidth to sm or md to render compact square boards centered instead of stretching full-width; lg is the default full-width behavior. Cell color and textColor are palette names or literal #rrggbb hex values (hex ignores page accent); textColor overrides the default auto-contrast text color. Two interaction modes: leave select 'off' and bind on.press to fire an action per cell press (inputs[name] is the pressed 'row,col' before the action runs); or set select 'single'/'multiple' for press-to-select with a visual ring (no auto-fire — pair with a separate submit button). on.press is ignored when select is on.",
         },
     },
     actions: {
@@ -146,5 +151,17 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
                 buyToken: z.string().optional(),
             }),
         },
+        paginator_next: {
+            description: "Move the snap's paginator to the next page locally. Does not POST and is ignored when no paginator is rendered.",
+            params: z.object({ page: z.number().int().min(0).optional() }),
+        },
+        paginator_prev: {
+            description: "Move the snap's paginator to the previous page locally. Does not POST and is ignored when no paginator is rendered.",
+            params: z.object({ page: z.number().int().min(0).optional() }),
+        },
+        paginator_go_to: {
+            description: "Move the snap's paginator to a specific zero-based page index locally. Does not POST and is ignored when no paginator is rendered.",
+            params: z.object({ page: z.number().int().min(0) }),
+        },
     },
 });

package/dist/ui/cell-grid.d.ts

@@ -40,6 +40,11 @@ export declare const cellGridProps: z.ZodObject<{
         square: "square";
     }>>;
     rowHeight: z.ZodOptional<z.ZodNumber>;
+    maxWidth: z.ZodOptional<z.ZodEnum<{
+        sm: "sm";
+        md: "md";
+        lg: "lg";
+    }>>;
     select: z.ZodOptional<z.ZodEnum<{
         multiple: "multiple";
         off: "off";

package/dist/ui/cell-grid.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { isSnapHexColorString, PALETTE_COLOR_VALUES } from "../colors.js";
-import { GRID_MIN_COLS, GRID_MAX_COLS, GRID_MIN_ROWS, GRID_MAX_ROWS, GRID_GAP_VALUES, GRID_CELL_ASPECT_RATIO_VALUES, } from "../constants.js";
+import { GRID_MIN_COLS, GRID_MAX_COLS, GRID_MIN_ROWS, GRID_MAX_ROWS, GRID_GAP_VALUES, GRID_CELL_ASPECT_RATIO_VALUES, GRID_MAX_WIDTH_VALUES, } from "../constants.js";
 /** Palette name or `#rrggbb`; input is trimmed so palette and hex rules match runtime resolvers. */
 const cellGridCellColorSchema = (field) => z.preprocess((v) => (typeof v === "string" ? v.trim() : v), z.union([
     z.enum(PALETTE_COLOR_VALUES),
@@ -25,6 +25,7 @@ export const cellGridProps = z
     gap: z.enum(GRID_GAP_VALUES).optional(),
     cellAspectRatio: z.enum(GRID_CELL_ASPECT_RATIO_VALUES).optional(),
     rowHeight: z.number().int().min(8).max(64).optional(),
+    maxWidth: z.enum(GRID_MAX_WIDTH_VALUES).optional(),
     select: z.enum(["off", "single", "multiple"]).optional(),
 })
     .superRefine((val, ctx) => {

package/dist/ui/image.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-export declare const IMAGE_ASPECTS: readonly ["1:1", "16:9", "4:3", "9:16"];
+export declare const IMAGE_ASPECTS: readonly ["1:1", "16:9", "4:3", "9:16", "4:1"];
 export declare const imageProps: z.ZodObject<{
     url: z.ZodString;
     aspect: z.ZodEnum<{
@@ -7,7 +7,10 @@ export declare const imageProps: z.ZodObject<{
         "16:9": "16:9";
         "4:3": "4:3";
         "9:16": "9:16";
+        "4:1": "4:1";
     }>;
     alt: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    subtitle: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ImageProps = z.infer<typeof imageProps>;

package/dist/ui/image.js

@@ -1,7 +1,9 @@
 import { z } from "zod";
-export const IMAGE_ASPECTS = ["1:1", "16:9", "4:3", "9:16"];
+export const IMAGE_ASPECTS = ["1:1", "16:9", "4:3", "9:16", "4:1"];
 export const imageProps = z.object({
     url: z.string(),
     aspect: z.enum(IMAGE_ASPECTS),
     alt: z.string().optional(),
+    title: z.string().min(1).max(80).optional(),
+    subtitle: z.string().min(1).max(120).optional(),
 });

package/dist/ui/index.d.ts

@@ -18,6 +18,8 @@ export { iconProps, ICON_NAMES } from "./icon.js";
 export type { IconProps } from "./icon.js";
 export { imageProps } from "./image.js";
 export type { ImageProps } from "./image.js";
+export { paginatorProps } from "./paginator.js";
+export type { PaginatorProps } from "./paginator.js";
 export { progressProps } from "./progress.js";
 export type { ProgressProps } from "./progress.js";
 export { separatorProps } from "./separator.js";

package/dist/ui/index.js

@@ -9,6 +9,7 @@ export { itemProps, itemMediaProps } from "./item.js";
 export { itemGroupProps } from "./item-group.js";
 export { iconProps, ICON_NAMES } from "./icon.js";
 export { imageProps } from "./image.js";
+export { paginatorProps } from "./paginator.js";
 export { progressProps } from "./progress.js";
 export { separatorProps } from "./separator.js";
 export { sliderProps } from "./slider.js";

package/dist/ui/paginator-state.d.ts

@@ -0,0 +1,18 @@
+export declare const SNAP_PAGINATOR_PAGE_PATH = "/ui/paginator/page";
+export declare const SNAP_PAGINATOR_PAGE_COUNT_PATH = "/ui/paginator/pageCount";
+export type SnapPaginatorAction = {
+    action: "paginator_next" | "paginator_prev";
+} | {
+    action: "paginator_go_to";
+    page?: number;
+};
+type StateStoreAccess = {
+    get: (path: string) => unknown;
+    set: (path: string, value: unknown) => void;
+};
+export declare function clampPaginatorPage(value: number, pageCount: number): number;
+export declare function pageFromValue(value: unknown, fallback?: number): number;
+export declare function pageCountFromValue(value: unknown): number;
+export declare function getPaginatorAction(on: Record<string, unknown> | undefined): SnapPaginatorAction | null;
+export declare function runPaginatorAction(store: StateStoreAccess, action: SnapPaginatorAction | null): boolean;
+export {};

package/dist/ui/paginator-state.js

@@ -0,0 +1,47 @@
+export const SNAP_PAGINATOR_PAGE_PATH = "/ui/paginator/page";
+export const SNAP_PAGINATOR_PAGE_COUNT_PATH = "/ui/paginator/pageCount";
+export function clampPaginatorPage(value, pageCount) {
+    return Math.min(Math.max(value, 0), Math.max(pageCount - 1, 0));
+}
+export function pageFromValue(value, fallback = 0) {
+    return typeof value === "number" && Number.isInteger(value)
+        ? value
+        : fallback;
+}
+export function pageCountFromValue(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0
+        ? value
+        : 0;
+}
+export function getPaginatorAction(on) {
+    const press = on?.press;
+    if (!press)
+        return null;
+    if (press.action === "paginator_next")
+        return { action: "paginator_next" };
+    if (press.action === "paginator_prev")
+        return { action: "paginator_prev" };
+    if (press.action === "paginator_go_to") {
+        const page = press.params?.page;
+        return {
+            action: "paginator_go_to",
+            page: typeof page === "number" && Number.isInteger(page) ? page : 0,
+        };
+    }
+    return null;
+}
+export function runPaginatorAction(store, action) {
+    if (!action)
+        return false;
+    const pageCount = pageCountFromValue(store.get(SNAP_PAGINATOR_PAGE_COUNT_PATH));
+    if (pageCount === 0)
+        return false;
+    const currentPage = clampPaginatorPage(pageFromValue(store.get(SNAP_PAGINATOR_PAGE_PATH), 0), pageCount);
+    const nextPage = action.action === "paginator_next"
+        ? currentPage + 1
+        : action.action === "paginator_prev"
+            ? currentPage - 1
+            : action.page ?? 0;
+    store.set(SNAP_PAGINATOR_PAGE_PATH, clampPaginatorPage(nextPage, pageCount));
+    return true;
+}

package/dist/ui/paginator.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+export declare const paginatorProps: z.ZodObject<{
+    initialPage: z.ZodOptional<z.ZodNumber>;
+    showIndicators: z.ZodOptional<z.ZodBoolean>;
+    showControls: z.ZodOptional<z.ZodBoolean>;
+    controlsPosition: z.ZodOptional<z.ZodEnum<{
+        top: "top";
+        bottom: "bottom";
+    }>>;
+    transition: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        slide: "slide";
+        fade: "fade";
+        scale: "scale";
+    }>>;
+}, z.core.$strip>;
+export type PaginatorProps = z.infer<typeof paginatorProps>;

package/dist/ui/paginator.js

@@ -0,0 +1,8 @@
+import { z } from "zod";
+export const paginatorProps = z.object({
+    initialPage: z.number().int().min(0).optional(),
+    showIndicators: z.boolean().optional(),
+    showControls: z.boolean().optional(),
+    controlsPosition: z.enum(["top", "bottom"]).optional(),
+    transition: z.enum(["slide", "fade", "scale", "none"]).optional(),
+});

package/dist/ui/text.d.ts

@@ -18,5 +18,6 @@ export declare const textProps: z.ZodObject<{
         left: "left";
         right: "right";
     }>>;
+    maxLines: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type TextProps = z.infer<typeof textProps>;

package/dist/ui/text.js

@@ -8,4 +8,5 @@ export const textProps = z.object({
     size: z.enum(TEXT_SIZES).optional(),
     weight: z.enum(TEXT_WEIGHTS).optional(),
     align: z.enum(TEXT_ALIGNS).optional(),
+    maxLines: z.number().int().min(1).max(6).optional(),
 });

package/dist/validator.js

@@ -76,9 +76,12 @@ function validateStructure(ui) {
             path: ["ui", "elements"],
         });
     }
-    // Root element has a stricter children limit
+    // Root element has a stricter children limit. Paginator pages are intentionally
+    // allowed to exceed per-container child caps while preserving global limits.
     const rootEl = elements[ui.root];
-    if (rootEl?.children && rootEl.children.length > MAX_ROOT_CHILDREN) {
+    if (rootEl?.type !== "paginator" &&
+        rootEl?.children &&
+        rootEl.children.length > MAX_ROOT_CHILDREN) {
         issues.push({
             code: "custom",
             message: `Root element "${ui.root}" exceeds maximum of ${MAX_ROOT_CHILDREN} children (found ${rootEl.children.length})`,
@@ -88,7 +91,7 @@ function validateStructure(ui) {
     for (const [id, el] of Object.entries(elements)) {
         if (id === ui.root)
             continue; // already checked above
-        if (el.children && el.children.length > MAX_CHILDREN) {
+        if (el.type !== "paginator" && el.children && el.children.length > MAX_CHILDREN) {
             issues.push({
                 code: "custom",
                 message: `Element "${id}" exceeds maximum of ${MAX_CHILDREN} children (found ${el.children.length})`,
@@ -96,6 +99,16 @@ function validateStructure(ui) {
             });
         }
     }
+    const paginatorIds = Object.entries(elements)
+        .filter(([, el]) => el.type === "paginator")
+        .map(([id]) => id);
+    if (paginatorIds.length > 1) {
+        issues.push({
+            code: "custom",
+            message: `Snap supports at most one paginator (found ${paginatorIds.length}: ${paginatorIds.join(", ")})`,
+            path: ["ui", "elements"],
+        });
+    }
     const depth = measureDepth(elements, ui.root);
     if (depth > MAX_DEPTH) {
         issues.push({

package/llms.txt

@@ -36,10 +36,10 @@ Top-level fields: `version` (required, `"1.0"` or `"2.0"`), `theme` (optional, `
 |------------|-------|
 | Total elements | Max **64** in `ui.elements` |
 | Root children | Max **7** children on the root element |
-| Children per element | Max **6** per non-root container (`stack`, `item_group`) |
+| Children per element | Max **6** per non-root container (`stack`, `item_group`); `paginator` pages are exempt |
 | Nesting depth | Max **5** levels from root to deepest leaf |
 
-## Components (16 total)
+## Components (17 total)
 
 ### Display Components
 
@@ -61,8 +61,9 @@ Top-level fields: `version` (required, `"1.0"` or `"2.0"`), `theme` (optional, `
 
 **image** — HTTPS image with fixed aspect ratio.
 - `url` (string, required)
-- `aspect` (required): `"1:1"` | `"16:9"` | `"4:3"` | `"9:16"`
+- `aspect` (required): `"1:1"` | `"16:9"` | `"4:3"` | `"9:16"` | `"4:1"`
 - `alt` (string, optional)
+- `title` (string, optional, max 80) and `subtitle` (string, optional, max 120) render readable overlay text. Use this for hero-like image titles; do not create a separate hero component.
 
 **item** — Content row matching shadcn Item: optional left media, content, and right-side actions slot.
 - `title` (string, required, max 100)
@@ -84,6 +85,7 @@ Top-level fields: `version` (required, `"1.0"` or `"2.0"`), `theme` (optional, `
 - `size` (optional): `"md"` (body) | `"sm"` (caption). Default: `"md"`
 - `weight` (optional): `"bold"` | `"normal"`. Default: `"normal"`
 - `align` (optional): `"left"` | `"center"` | `"right"`. Default: `"left"`
+- `maxLines` (optional): integer 1–6. Default: no clamp. Set this when body text should use a bounded number of visible lines.
 
 ### Data Components
 
@@ -100,14 +102,27 @@ Top-level fields: `version` (required, `"1.0"` or `"2.0"`), `theme` (optional, `
 - `gap` (optional): `"none"` (0px) | `"sm"` (1px) | `"md"` (2px) | `"lg"` (4px). Default: `"sm"`
 - `cellAspectRatio` (optional): `"auto"` | `"square"`. Default: `"auto"`. Use `"square"` for game boards whose cells must stay square as snap width changes.
 - `rowHeight` (number, optional, 8–64): pixel height per row. Default: 28. Grid height = rows × rowHeight
+- `maxWidth` (optional): `"sm"` | `"md"` | `"lg"`. Default: `"lg"` (full-width). Use `sm`/`md` with `cellAspectRatio: "square"` for small centered boards that should not stretch full-width.
 - `select` (optional): `"off"` | `"single"` | `"multiple"`. Default: `"off"`. With `select: "off"`, bind `on.press` for press-to-act (each press writes the cell's `value` or `"row,col"` to `inputs[name]` and fires the action). With `"single"` / `"multiple"`, presses accumulate selection state and pair with a separate submit `button` (multi-select joins values with `|`); `on.press` is ignored.
 - Events: `press` — fires on cell press, only when `select: "off"`; `inputs[name]` is set to the pressed cell's `value` (or `"row,col"` fallback) before the bound action runs
 
 ### Container Components
 
+**paginator** — Client-side page navigation without a server round trip.
+- Children are page element IDs; one child renders at a time.
+- `initialPage` (optional): zero-based page index. Default: `0`
+- `showIndicators` (optional): boolean. Default: `true`
+- `showControls` (optional): boolean. Default: `true`
+- `controlsPosition` (optional): `"top"` | `"bottom"`. Default: `"bottom"`. Moves the built-in pagination bar above or below page content; use `"top"` to keep controls stable when page heights vary.
+- `transition` (optional): `"slide"` | `"fade"` | `"scale"` | `"none"`. Default: `"slide"`. Controls the local page-change animation.
+- The current page is json-render local UI state only and is never included in POST `inputs`.
+- Set both `showControls: false` and `showIndicators: false` to hide the built-in pagination bar.
+- Buttons or tappable `cell_grid` cells anywhere in the same snap can bind local actions: `paginator_next` with `params: {}`, `paginator_prev` with `params: {}`, and `paginator_go_to` with `params: { "page": 0 }`. These affect the snap's rendered paginator, never POST, and support one paginator per snap in this release.
+- Paginator children may exceed the normal per-container child limit, but the snap still must stay within 64 total elements and max nesting depth.
+
 **stack** — Layout container.
 - `direction` (optional): `"vertical"` | `"horizontal"`. Default: `"vertical"`
-- `gap` (optional): `"none"` | `"sm"` | `"md"` | `"lg"`. Vertical px: 0/8/16/24. Horizontal px: 0/4/8/16 (tighter, since children sit side-by-side). Default for vertical: `"md"`. Default for horizontal is column-aware: 2 cols → `"lg"` (16px), 3 cols → `"md"` (8px), 4+ cols → `"sm"` (4px), unknown → `"md"` (8px). An explicit value always wins — override the default when you have a deliberate visual reason (e.g. tighter toolbar, extra breathing room around a hero row).
+- `gap` (optional): `"none"` | `"sm"` | `"md"` | `"lg"`. Vertical px: 0/4/16/24. Horizontal px: 0/4/8/16 (tighter, since children sit side-by-side). Default for vertical: `"md"`. Default for horizontal is column-aware: 2 cols → `"lg"` (16px), 3 cols → `"md"` (8px), 4+ cols → `"sm"` (4px), unknown → `"md"` (8px). An explicit value always wins — override the default when you have a deliberate visual reason (e.g. tighter toolbar, extra breathing room around a hero row).
 - `justify` (optional): `"start"` | `"center"` | `"end"` | `"between"` | `"around"`
 - `columns` (optional, horizontal only): `2`–`6` — CSS grid with equal columns (mixed children or layout that needs fixed column counts).
 - Children are element IDs

package/package.json

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

package/src/constants.ts

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

package/src/react/catalog-renderer.tsx

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