@farcaster/snap 2.5.1 → 2.6.1

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

@@ -7,8 +7,7 @@ import {
   resolveAccentHex,
 } from "../snap-view-core";
 import type { SnapPage, SnapActionHandlers } from "../types";
-
-const SNAP_MAX_HEIGHT = 500;
+import { getSnapExpansionState } from "../expand-state";
 
 // ─── SnapViewV1 (no validation) ──────────────────────
 
@@ -72,6 +71,9 @@ function SnapCardV1Inner({
   appearance,
   plain,
   loadingOverlay,
+  forceExpanded,
+  expandButtonLabel,
+  onExpandPress,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -81,6 +83,9 @@ function SnapCardV1Inner({
   appearance: "light" | "dark";
   plain: boolean;
   loadingOverlay?: ReactNode;
+  forceExpanded?: boolean;
+  expandButtonLabel?: string;
+  onExpandPress?: () => void;
 }) {
   const { colors, mode } = useSnapTheme();
   const accentHex = resolveAccentHex(snap.theme?.accent, mode);
@@ -92,8 +97,14 @@ function SnapCardV1Inner({
     setContentHeight(0);
   }, [snap]);
 
-  const isExpandable = contentHeight > SNAP_MAX_HEIGHT + 1;
-  const isClipped = isExpandable && !isExpanded;
+  const expansion = getSnapExpansionState({
+    contentHeight,
+    internalExpanded: isExpanded,
+    forceExpanded,
+    onExpandPress,
+    expandButtonLabel,
+  });
+  const expandButtonInsideCard = typeof onExpandPress === "function";
 
   const isDark = mode === "dark";
   const pillBg = isDark ? "rgba(40,40,40,0.92)" : "rgba(255,255,255,0.92)";
@@ -112,14 +123,18 @@ function SnapCardV1Inner({
           ]}
         >
           <View
-            style={isClipped ? { maxHeight: SNAP_MAX_HEIGHT, overflow: "hidden" } : undefined}
+            style={
+              expansion.clipped
+                ? { maxHeight: expansion.maxHeight, overflow: "hidden" }
+                : undefined
+            }
           >
             <View
               collapsable={false}
               onLayout={(event) => {
                 const nextHeight = Math.round(event.nativeEvent.layout.height);
                 setContentHeight((currentHeight) =>
-                  isClipped
+                  expansion.clipped
                     ? Math.max(currentHeight, nextHeight)
                     : currentHeight === nextHeight
                       ? currentHeight
@@ -142,8 +157,15 @@ function SnapCardV1Inner({
               : loadingOverlay
             : null}
         </View>
-        {isExpandable ? (
-          <View pointerEvents="box-none" style={cardStyles.expandFloat}>
+        {expansion.showButton ? (
+          <View
+            pointerEvents="box-none"
+            style={
+              expandButtonInsideCard
+                ? cardStyles.expandFloatInset
+                : cardStyles.expandFloat
+            }
+          >
             <Pressable
               style={({ pressed }) => [
                 cardStyles.expandButton,
@@ -153,13 +175,17 @@ function SnapCardV1Inner({
                 },
               ]}
               onPress={() => {
-                setIsExpanded((value) => !value);
+                if (expansion.useInternalToggle) {
+                  setIsExpanded((value) => !value);
+                } else {
+                  onExpandPress?.();
+                }
               }}
             >
               <Text
                 style={[cardStyles.expandButtonText, { color: colors.text }]}
               >
-                {isExpanded ? "Show less" : "Show more"}
+                {expansion.buttonLabel}
               </Text>
             </Pressable>
           </View>
@@ -194,6 +220,9 @@ export function SnapCardV1({
   actionError,
   plain = false,
   loadingOverlay,
+  forceExpanded,
+  expandButtonLabel,
+  onExpandPress,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -205,6 +234,12 @@ export function SnapCardV1({
   plain?: boolean;
   /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
   loadingOverlay?: ReactNode;
+  /** When true, render full content height without 500px clipping or expand controls. */
+  forceExpanded?: boolean;
+  /** Custom label for the collapsed expand button. */
+  expandButtonLabel?: string;
+  /** Called from the collapsed expand button instead of toggling internal state. */
+  onExpandPress?: () => void;
 }) {
   return (
     <SnapThemeProvider appearance={appearance} colors={colors}>
@@ -217,6 +252,9 @@ export function SnapCardV1({
         appearance={appearance}
         plain={plain}
         loadingOverlay={loadingOverlay}
+        forceExpanded={forceExpanded}
+        expandButtonLabel={expandButtonLabel}
+        onExpandPress={onExpandPress}
       />
     </SnapThemeProvider>
   );
@@ -235,6 +273,15 @@ const cardStyles = StyleSheet.create({
     alignItems: "center",
     justifyContent: "center",
   },
+  expandFloatInset: {
+    position: "absolute",
+    left: 0,
+    right: 0,
+    bottom: 10,
+    height: 28,
+    alignItems: "center",
+    justifyContent: "center",
+  },
   expandButton: {
     minWidth: 92,
     alignItems: "center",

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

@@ -12,10 +12,10 @@ import {
   type ValidationResult,
 } from "@farcaster/snap";
 import type { SnapPage, SnapActionHandlers } from "../types";
+import { getSnapExpansionState, SNAP_MAX_HEIGHT } from "../expand-state";
 
 // ─── Constants ───────────────────────────────────────
 
-const SNAP_MAX_HEIGHT = 500;
 const SNAP_WARNING_HEIGHT = 700;
 const SHOW_MORE_OVERHANG = 14;
 
@@ -141,6 +141,9 @@ function SnapCardV2Inner({
   appearance,
   plain,
   loadingOverlay,
+  forceExpanded,
+  expandButtonLabel,
+  onExpandPress,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -153,6 +156,9 @@ function SnapCardV2Inner({
   appearance: "light" | "dark";
   plain: boolean;
   loadingOverlay?: ReactNode;
+  forceExpanded?: boolean;
+  expandButtonLabel?: string;
+  onExpandPress?: () => void;
 }) {
   const { colors, mode } = useSnapTheme();
   const accentHex = resolveAccentHex(snap.theme?.accent, mode);
@@ -164,8 +170,15 @@ function SnapCardV2Inner({
     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 = (
     <SnapViewV2Inner
@@ -181,13 +194,19 @@ function SnapCardV2Inner({
   if (plain) {
     return (
       <>
-        <View style={isClipped ? { maxHeight: SNAP_MAX_HEIGHT, overflow: "hidden" } : undefined}>
+        <View
+          style={
+            expansion.clipped
+              ? { maxHeight: expansion.maxHeight, overflow: "hidden" }
+              : undefined
+          }
+        >
           <View
             collapsable={false}
             onLayout={(e) => {
               const nextHeight = Math.round(e.nativeEvent.layout.height);
               setContentHeight((current) =>
-                isClipped
+                expansion.clipped
                   ? Math.max(current, nextHeight)
                   : current === nextHeight
                     ? current
@@ -203,7 +222,7 @@ function SnapCardV2Inner({
             ? <SnapLoadingOverlay appearance={mode} accentHex={accentHex} />
             : loadingOverlay
           : null}
-        {isExpandable ? (
+        {expansion.showButton ? (
           <View style={[cardStyles.expandRow, cardStyles.expandRowPlain]}>
             <Pressable
               style={({ pressed }) => [
@@ -212,10 +231,16 @@ function SnapCardV2Inner({
                   backgroundColor: pressed ? colors.mutedHover : colors.muted,
                 },
               ]}
-              onPress={() => setIsExpanded((value) => !value)}
+              onPress={() => {
+                if (expansion.useInternalToggle) {
+                  setIsExpanded((value) => !value);
+                } else {
+                  onExpandPress?.();
+                }
+              }}
             >
               <Text style={[cardStyles.expandButtonText, { color: colors.text }]}>
-                {isExpanded ? "Show less" : "Show more"}
+                {expansion.buttonLabel}
               </Text>
             </Pressable>
           </View>
@@ -224,13 +249,20 @@ function SnapCardV2Inner({
     );
   }
 
-  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 (
-    <View style={{ paddingBottom: isExpandable ? SHOW_MORE_OVERHANG : 0 }}>
+    <View
+      style={{
+        paddingBottom:
+          expansion.showButton && !expandButtonInsideCard ? SHOW_MORE_OVERHANG : 0,
+      }}
+    >
       <View style={{ position: "relative" }}>
         <View
           style={{
@@ -238,7 +270,9 @@ function SnapCardV2Inner({
             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,
           }}
@@ -248,7 +282,7 @@ function SnapCardV2Inner({
             onLayout={(e) => {
               const nextHeight = Math.round(e.nativeEvent.layout.height);
               setContentHeight((current) =>
-                isClipped
+                expansion.clipped
                   ? Math.max(current, nextHeight)
                   : current === nextHeight
                     ? current
@@ -259,7 +293,7 @@ function SnapCardV2Inner({
           >
             {content}
           </View>
-          {showOverflowWarning && contentHeight > SNAP_MAX_HEIGHT && (
+          {expansion.showOverflowWarning && contentHeight > SNAP_MAX_HEIGHT && (
             <View style={{ position: "absolute", top: SNAP_MAX_HEIGHT, left: 0, right: 0, height: overflowAmount, zIndex: 10, pointerEvents: "none" }}>
               <View style={{ height: 1, borderTopWidth: 1, borderStyle: "dashed", borderColor: "rgba(255,100,100,0.6)" }} />
               <View style={{ position: "absolute", top: -10, right: 4, backgroundColor: "rgba(0,0,0,0.7)", paddingHorizontal: 4, paddingVertical: 1, borderRadius: 3 }}>
@@ -274,8 +308,15 @@ function SnapCardV2Inner({
               : loadingOverlay
             : null}
         </View>
-        {isExpandable ? (
-          <View pointerEvents="box-none" style={cardStyles.expandFloat}>
+        {expansion.showButton ? (
+          <View
+            pointerEvents="box-none"
+            style={
+              expandButtonInsideCard
+                ? cardStyles.expandFloatInset
+                : cardStyles.expandFloat
+            }
+          >
             <Pressable
               style={({ pressed }) => [
                 cardStyles.expandButton,
@@ -284,10 +325,16 @@ function SnapCardV2Inner({
                   borderColor: colors.border,
                 },
               ]}
-              onPress={() => setIsExpanded((value) => !value)}
+              onPress={() => {
+                if (expansion.useInternalToggle) {
+                  setIsExpanded((value) => !value);
+                } else {
+                  onExpandPress?.();
+                }
+              }}
             >
               <Text style={[cardStyles.expandButtonText, { color: colors.text }]}>
-                {isExpanded ? "Show less" : "Show more"}
+                {expansion.buttonLabel}
               </Text>
             </Pressable>
           </View>
@@ -325,6 +372,9 @@ export function SnapCardV2({
   actionError,
   plain = false,
   loadingOverlay,
+  forceExpanded,
+  expandButtonLabel,
+  onExpandPress,
 }: {
   snap: SnapPage;
   handlers: SnapActionHandlers;
@@ -339,6 +389,12 @@ export function SnapCardV2({
   plain?: boolean;
   /** Custom content rendered while `loading` is true. Pass `null` to render nothing. */
   loadingOverlay?: ReactNode;
+  /** When true, render full content height without 500px clipping or expand controls. */
+  forceExpanded?: boolean;
+  /** Custom label for the collapsed expand button. */
+  expandButtonLabel?: string;
+  /** Called from the collapsed expand button instead of toggling internal state. */
+  onExpandPress?: () => void;
 }) {
   return (
     <SnapThemeProvider appearance={appearance} colors={colors}>
@@ -354,6 +410,9 @@ export function SnapCardV2({
         appearance={appearance}
         plain={plain}
         loadingOverlay={loadingOverlay}
+        forceExpanded={forceExpanded}
+        expandButtonLabel={expandButtonLabel}
+        onExpandPress={onExpandPress}
       />
     </SnapThemeProvider>
   );
@@ -373,6 +432,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/src/ui/catalog.ts

@@ -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";
@@ -72,7 +73,13 @@ 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,
@@ -97,7 +104,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
     text: {
       props: textProps,
       description:
-        "Text block — size: md (body, default), sm (caption). Optional weight and align.",
+        "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,
@@ -107,7 +114,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.",
+        "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: {
@@ -165,5 +172,20 @@ 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/src/ui/cell-grid.ts

@@ -7,6 +7,7 @@ import {
   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. */
@@ -38,6 +39,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/src/ui/image.ts

@@ -1,11 +1,13 @@
 import { z } from "zod";
 
-export const IMAGE_ASPECTS = ["1:1", "16:9", "4:3", "9:16"] as const;
+export const IMAGE_ASPECTS = ["1:1", "16:9", "4:3", "9:16", "4:1"] as const;
 
 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(),
 });
 
 export type ImageProps = z.infer<typeof imageProps>;

package/src/ui/index.ts

@@ -28,6 +28,9 @@ 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";
 

package/src/ui/paginator-state.ts

@@ -0,0 +1,67 @@
+export const SNAP_PAGINATOR_PAGE_PATH = "/ui/paginator/page";
+export 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 function clampPaginatorPage(value: number, pageCount: number): number {
+  return Math.min(Math.max(value, 0), Math.max(pageCount - 1, 0));
+}
+
+export function pageFromValue(value: unknown, fallback = 0): number {
+  return typeof value === "number" && Number.isInteger(value)
+    ? value
+    : fallback;
+}
+
+export function pageCountFromValue(value: unknown): number {
+  return typeof value === "number" && Number.isInteger(value) && value > 0
+    ? value
+    : 0;
+}
+
+export function getPaginatorAction(
+  on: Record<string, unknown> | undefined,
+): SnapPaginatorAction | null {
+  const press = on?.press as
+    | { action?: string; params?: Record<string, unknown> }
+    | undefined;
+  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: StateStoreAccess,
+  action: SnapPaginatorAction | null,
+): boolean {
+  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 as { action: "paginator_go_to"; page?: number }).page ?? 0;
+  store.set(SNAP_PAGINATOR_PAGE_PATH, clampPaginatorPage(nextPage, pageCount));
+  return true;
+}

package/src/ui/paginator.ts

@@ -0,0 +1,11 @@
+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(),
+});
+
+export type PaginatorProps = z.infer<typeof paginatorProps>;

package/src/ui/text.ts

@@ -10,6 +10,7 @@ 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(),
 });
 
 export type TextProps = z.infer<typeof textProps>;

package/src/validator.ts

@@ -119,9 +119,14 @@ function validateStructure(ui: {
     });
   }
 
-  // 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})`,
@@ -131,7 +136,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})`,
@@ -140,6 +145,17 @@ 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 as Record<string, { children?: string[] }>,
     ui.root,