@farcaster/snap 2.4.0 → 2.5.0

package/src/react-native/components/snap-item-group.tsx

@@ -2,8 +2,14 @@ import type { ComponentRenderProps } from "@json-render/react-native";
 import { Children, Fragment, type ReactNode } from "react";
 import { StyleSheet, View } from "react-native";
 import { useSnapTheme } from "../theme";
+import { SnapItemGroupBorderProvider } from "./item-layout-context";
 
-const GAP_MAP: Record<string, number> = { none: 0, sm: 4, md: 8, lg: 12 };
+const GAP_MAP: Record<string, number> = {
+  none: 0,
+  sm: 4,
+  md: 8,
+  lg: 12,
+};
 
 export function SnapItemGroup({
   element: { props },
@@ -16,22 +22,30 @@ export function SnapItemGroup({
   const items = Children.toArray(children);
 
   return (
-    <View
-      style={[
-        styles.group,
-        border && { borderWidth: 1, borderColor: colors.border, borderRadius: 12 },
-        { gap },
-      ]}
-    >
-      {items.map((child, i) => (
-        <Fragment key={i}>
-          {separator && i > 0 && (
-            <View style={{ height: 1, backgroundColor: colors.border + "80" }} />
-          )}
-          {child}
-        </Fragment>
-      ))}
-    </View>
+    <SnapItemGroupBorderProvider value={border}>
+      <View
+        style={[
+          styles.group,
+          border && {
+            borderWidth: 1,
+            borderColor: colors.border,
+            borderRadius: 12,
+          },
+          { gap },
+        ]}
+      >
+        {items.map((child, i) => (
+          <Fragment key={i}>
+            {separator && i > 0 && (
+              <View
+                style={{ height: 1, backgroundColor: colors.border + "80" }}
+              />
+            )}
+            {child}
+          </Fragment>
+        ))}
+      </View>
+    </SnapItemGroupBorderProvider>
   );
 }
 

package/src/react-native/components/snap-item.tsx

@@ -1,33 +1,98 @@
 import type { ComponentRenderProps } from "@json-render/react-native";
+import { Image } from "expo-image";
 import type { ReactNode } from "react";
 import { StyleSheet, Text, View } from "react-native";
 import { useSnapStackDirection } from "../stack-direction-context";
 import { useSnapTheme } from "../theme";
+import { useSnapPalette } from "../use-snap-palette";
+import { useSnapItemGroupHasBorder } from "./item-layout-context";
+import { ICON_MAP } from "./snap-icon";
+
+type ItemMediaConfig =
+  | {
+      variant: "icon";
+      name: string;
+      color?: string;
+    }
+  | {
+      variant: "image";
+      url: string;
+      alt?: string;
+      round?: boolean;
+    };
+
+function parseItemMedia(value: unknown): ItemMediaConfig | undefined {
+  if (!value || typeof value !== "object") return undefined;
+
+  const media = value as Record<string, unknown>;
+  if (media.variant === "icon" && typeof media.name === "string") {
+    return {
+      variant: "icon",
+      name: media.name,
+      color: typeof media.color === "string" ? media.color : undefined,
+    };
+  }
+
+  if (media.variant === "image" && typeof media.url === "string") {
+    return {
+      variant: "image",
+      url: media.url,
+      alt: typeof media.alt === "string" ? media.alt : undefined,
+      round: typeof media.round === "boolean" ? media.round : undefined,
+    };
+  }
+
+  return undefined;
+}
 
 export function SnapItem({
   element: { props },
   children,
 }: ComponentRenderProps<Record<string, unknown>> & { children?: ReactNode }) {
   const { colors } = useSnapTheme();
+  const { accentHex, hex } = useSnapPalette();
   const title = String(props.title ?? "");
-  const description = props.description
-    ? String(props.description)
-    : undefined;
+  const description = props.description ? String(props.description) : undefined;
+  const media = parseItemMedia(props.media);
+  const inBorderedGroup = useSnapItemGroupHasBorder();
   /** Match web `Item className="flex-1"`: row peers must share width or title/description collapse. */
   const rowPeer = useSnapStackDirection() === "horizontal";
+  const MediaIcon =
+    media?.variant === "icon" ? ICON_MAP[media.name] : undefined;
+  const mediaColor =
+    media?.variant === "icon" && media.color && media.color !== "accent"
+      ? hex(media.color)
+      : accentHex;
 
-  const containerVariant = { paddingVertical: 6, paddingHorizontal: 10 };
+  const containerVariant = {
+    paddingVertical: 6,
+    paddingHorizontal: inBorderedGroup ? 8 : 0,
+    columnGap: 8,
+  };
 
   return (
     <View
-      style={[
-        styles.container,
-        containerVariant,
-        rowPeer && styles.rowPeer,
-      ]}
+      style={[styles.container, containerVariant, rowPeer && styles.rowPeer]}
     >
+      {media?.variant === "icon" && MediaIcon ? (
+        <View style={styles.iconMedia}>
+          <MediaIcon size={20} color={mediaColor} />
+        </View>
+      ) : null}
+      {media?.variant === "image" ? (
+        <View style={[styles.imageMedia, media.round && styles.roundImage]}>
+          <Image
+            source={{ uri: media.url }}
+            style={StyleSheet.absoluteFill}
+            contentFit="cover"
+            accessibilityLabel={media.alt || undefined}
+          />
+        </View>
+      ) : null}
       <View style={styles.content}>
-        {title ? <Text style={[styles.title, { color: colors.text }]}>{title}</Text> : null}
+        {title ? (
+          <Text style={[styles.title, { color: colors.text }]}>{title}</Text>
+        ) : null}
         {description ? (
           <Text style={[styles.description, { color: colors.textSecondary }]}>
             {description}
@@ -55,19 +120,32 @@ const styles = StyleSheet.create({
   content: {
     flex: 1,
   },
+  iconMedia: {
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  imageMedia: {
+    width: 40,
+    height: 40,
+    borderRadius: 6,
+    overflow: "hidden",
+    backgroundColor: "#f3f4f6",
+  },
+  roundImage: {
+    borderRadius: 9999,
+  },
   title: {
     fontSize: 15,
     lineHeight: 20,
     fontWeight: "500",
   },
   description: {
-    fontSize: 13,
-    lineHeight: 18,
-    marginTop: 1,
+    fontSize: 12,
+    lineHeight: 16,
   },
   actions: {
     marginLeft: "auto",
-    paddingLeft: 12,
+    paddingLeft: 8,
     flexDirection: "row",
     alignItems: "center",
     flexShrink: 0,

package/src/react-native/components/snap-stack.tsx

@@ -2,9 +2,10 @@ import type { ComponentRenderProps } from "@json-render/react-native";
 import { Children, type ReactNode } from "react";
 import { StyleSheet, View } from "react-native";
 import {
+  childrenShouldUseHorizontalButtonLayout,
+  childrenAreAllButtons,
   countRenderableChildren,
   defaultHorizontalGapSize,
-  horizontalChildrenAreAllButtons,
 } from "../../stack-horizontal-utils.js";
 import {
   SnapStackDirectionProvider,
@@ -13,7 +14,7 @@ import {
 
 const VGAP: Record<string, number> = {
   none: 0,
-  sm: 8,
+  sm: 4,
   md: 16,
   lg: 24,
 };
@@ -33,7 +34,7 @@ const JUSTIFY: Record<string, "flex-start" | "center" | "flex-end" | "space-betw
   around: "space-around",
 };
 
-/** Equal-width cells for explicit `columns` and all-button horizontal rows. */
+/** Equal-width cells for explicit `equalWidth` / `columns` props. */
 function wrapEqualColumnCells(children: ReactNode): ReactNode {
   const cells = Children.toArray(children).filter(
     (c) => c != null && c !== false,
@@ -50,17 +51,21 @@ export function SnapStack({
   children,
 }: ComponentRenderProps<Record<string, unknown>> & { children?: ReactNode }) {
   const parentDirection = useSnapStackDirection();
-  const direction = String(props.direction ?? "vertical");
+  const buttonContentUsesHorizontal =
+    childrenShouldUseHorizontalButtonLayout(children);
+  const direction =
+    buttonContentUsesHorizontal === undefined
+      ? String(props.direction ?? "vertical")
+      : buttonContentUsesHorizontal
+        ? "horizontal"
+        : "vertical";
   const rawGap = props.gap;
   const isHorizontal = direction === "horizontal";
   const gapMap = isHorizontal ? HGAP : VGAP;
-  const buttonRowGrid =
-    isHorizontal && horizontalChildrenAreAllButtons(children);
-  const buttonRowCount = buttonRowGrid
-    ? countRenderableChildren(children)
-    : 0;
+  const allChildrenAreButtons = childrenAreAllButtons(children);
 
   const columnsRaw = props.columns;
+  const equalWidth = props.equalWidth === true;
   const columns =
     typeof columnsRaw === "number" &&
     columnsRaw >= 2 &&
@@ -69,49 +74,44 @@ export function SnapStack({
       ? columnsRaw
       : undefined;
 
-  // Horizontal default depends on column count: 2→lg, 3→md, 4+→sm. Vertical stays md.
-  // Count comes from explicit `columns`, then button-row inference, else direct children
-  // count (any horizontal stack is N columns wide regardless of child types).
-  const horizontalColumnCount = isHorizontal
-    ? (columns ??
-       (buttonRowGrid ? buttonRowCount : undefined) ??
-       countRenderableChildren(children))
+  const equalWidthColumnCount =
+    columns ?? (equalWidth ? countRenderableChildren(children) : undefined);
+  const explicitEqualWidth =
+    isHorizontal &&
+    equalWidthColumnCount !== undefined &&
+    equalWidthColumnCount >= 1 &&
+    equalWidthColumnCount <= 6;
+
+  // Button-only stacks always default to sm; mixed horizontal stacks scale by child count.
+  // Vertical non-button stacks default to md.
+  const horizontalChildCount = isHorizontal
+    ? (explicitEqualWidth
+        ? equalWidthColumnCount
+        : countRenderableChildren(children))
     : undefined;
   const gap =
     typeof rawGap === "number"
       ? rawGap
       : typeof rawGap === "string" && rawGap in gapMap
         ? gapMap[rawGap]!
-        : isHorizontal
-          ? gapMap[defaultHorizontalGapSize(horizontalColumnCount)]!
+        : allChildrenAreButtons
+          ? gapMap.sm!
+          : isHorizontal
+          ? gapMap[defaultHorizontalGapSize(horizontalChildCount)]!
           : VGAP.md!;
-  const explicitColumnGrid =
-    isHorizontal && columns !== undefined && !buttonRowGrid;
-
   const justify =
     props.justify &&
-    (!isHorizontal || (!buttonRowGrid && !explicitColumnGrid))
+    (!isHorizontal || !explicitEqualWidth)
       ? JUSTIFY[String(props.justify)]
       : undefined;
 
   const isRowChild = parentDirection === "horizontal";
 
   const packedHorizontal =
-    isHorizontal &&
-    ((buttonRowGrid &&
-      buttonRowCount >= 1 &&
-      buttonRowCount <= 6) ||
-      explicitColumnGrid);
+    isHorizontal && explicitEqualWidth;
 
   let horizontalBody: ReactNode = children;
-  if (
-    isHorizontal &&
-    buttonRowGrid &&
-    buttonRowCount >= 1 &&
-    buttonRowCount <= 6
-  ) {
-    horizontalBody = wrapEqualColumnCells(children);
-  } else if (isHorizontal && explicitColumnGrid && columns !== undefined) {
+  if (isHorizontal && explicitEqualWidth) {
     horizontalBody = wrapEqualColumnCells(children);
   }
 
@@ -163,7 +163,7 @@ const styles = StyleSheet.create({
     width: "100%",
     minWidth: 0,
   },
-  /** Single row for packed equal-width cells (button grids & explicit columns). */
+  /** Single row for packed equal-width cells from explicit equal-width layout. */
   horizontalPacked: {
     flexDirection: "row",
     flexWrap: "nowrap",
@@ -176,5 +176,6 @@ const styles = StyleSheet.create({
     flexShrink: 1,
     flexBasis: 0,
     minWidth: 0,
+    alignSelf: "stretch",
   },
 });

package/src/react-native/components/snap-toggle-group.tsx

@@ -1,6 +1,7 @@
 import type { ComponentRenderProps } from "@json-render/react-native";
 import { useStateStore } from "@json-render/react-native";
 import { Pressable, StyleSheet, Text, View } from "react-native";
+import { shouldUseHorizontalButtonContent } from "../../button-orientation-utils.js";
 import { useSnapTheme } from "../theme";
 
 export function SnapToggleGroup({
@@ -12,7 +13,6 @@ export function SnapToggleGroup({
   const path = `/inputs/${name}`;
   const label = props.label ? String(props.label) : undefined;
   const isMultiple = Boolean(props.multiple);
-  const orientation = String(props.orientation ?? "horizontal");
   const options = Array.isArray(props.options)
     ? (props.options as string[])
     : [];
@@ -38,7 +38,7 @@ export function SnapToggleGroup({
     return [];
   })();
 
-  const isVertical = orientation === "vertical";
+  const isVertical = !shouldUseHorizontalButtonContent(options);
 
   const handlePress = (opt: string) => {
     if (isMultiple) {
@@ -65,7 +65,7 @@ export function SnapToggleGroup({
           const isSelected = selected.includes(opt);
           return (
             <Pressable
-              key={index}
+              key={`${opt}-${index}`}
               style={({ pressed }) => [
                 styles.option,
                 {
@@ -117,7 +117,8 @@ const styles = StyleSheet.create({
     justifyContent: "center",
   },
   optionHorizontal: {
-    flex: 1,
+    flexGrow: 1,
+    flexShrink: 1,
   },
   optionText: {
     fontSize: 13,

package/src/stack-horizontal-utils.ts

@@ -1,5 +1,7 @@
 import { Children, isValidElement, type ReactNode } from "react";
 
+import { shouldUseHorizontalButtonContent } from "./button-orientation-utils.js";
+
 /**
  * True when every rendered child comes from a catalog `button` element.
  * json-render passes `{ element: { type, props, ... } }` into each catalog component.
@@ -10,32 +12,49 @@ function isRenderableChild(c: ReactNode): boolean {
   return true;
 }
 
-export function horizontalChildrenAreAllButtons(children: ReactNode): boolean {
+export function childrenAreAllButtons(children: ReactNode): boolean {
+  return getButtonChildLabels(children) !== undefined;
+}
+
+export function getButtonChildLabels(children: ReactNode): string[] | undefined {
   const items = Children.toArray(children).filter(isRenderableChild);
-  if (items.length === 0) return false;
+  if (items.length === 0) return undefined;
+  const labels: string[] = [];
   for (const child of items) {
-    if (!isValidElement(child)) return false;
-    const typ = (child.props as { element?: { type?: unknown } }).element?.type;
-    if (typ !== "button") return false;
+    if (!isValidElement(child)) return undefined;
+    const element = (
+      child.props as {
+        element?: { type?: unknown; props?: Record<string, unknown> };
+      }
+    ).element;
+    if (element?.type !== "button") return undefined;
+    labels.push(String(element.props?.label ?? ""));
   }
-  return true;
+  return labels;
+}
+
+export function childrenShouldUseHorizontalButtonLayout(
+  children: ReactNode,
+): boolean | undefined {
+  const labels = getButtonChildLabels(children);
+  return labels ? shouldUseHorizontalButtonContent(labels) : undefined;
 }
 
-/** Direct snap catalog children under a stack (used for all-button grid column count). */
+/** Direct snap catalog children under a stack (used for horizontal gap defaults). */
 export function countRenderableChildren(children: ReactNode): number {
   return Children.toArray(children).filter(isRenderableChild).length;
 }
 
 /**
- * Default horizontal stack gap as a t-shirt size, chosen by column count:
- * 2 cols → lg, 3 cols → md, 4+ cols → sm. Unknown count falls back to md.
+ * Default horizontal stack gap as a t-shirt size, chosen by direct child count:
+ * 2 children → lg, 3 children → md, 4+ children → sm. Unknown count falls back to md.
  * Tighter gaps for denser layouts; authors can always override via the `gap` prop.
  */
 export function defaultHorizontalGapSize(
-  columnCount: number | undefined,
+  childCount: number | undefined,
 ): "sm" | "md" | "lg" {
-  if (columnCount === undefined) return "md";
-  if (columnCount <= 2) return "lg";
-  if (columnCount === 3) return "md";
+  if (childCount === undefined) return "md";
+  if (childCount <= 2) return "lg";
+  if (childCount === 3) return "md";
   return "sm";
 }

package/src/ui/catalog.ts

@@ -48,7 +48,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
     toggle_group: {
       props: toggleGroupProps,
       description:
-        "Single or multi-select choice group; `name` becomes POST inputs key. mode: single (default) | multiple. Optional label.",
+        "Single or multi-select choice group; `name` becomes POST inputs key. The @farcaster/snap React/React Native components choose row/column orientation from option label length, ignoring snap-sent orientation hints.",
     },
     input: {
       props: inputProps,
@@ -58,7 +58,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
     item: {
       props: itemProps,
       description:
-        "Content row with title and optional description. Children render in the actions slot (right side) — badge, button, and icon elements are all valid. The item itself is not interactive, so avoid navigation-style icons (`chevron-right`, `arrow-right`, `external-link`) that imply the row navigates.",
+        "Content row matching shadcn Item: optional media renders on the left, title and optional description render in the content area, and children render in the actions slot (right side). The item itself is not interactive, so avoid navigation-style icons (`chevron-right`, `arrow-right`, `external-link`) that imply the row navigates.",
     },
     item_group: {
       props: itemGroupProps,
@@ -92,7 +92,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
     stack: {
       props: stackProps,
       description:
-        "Layout container — direction: vertical (default) | horizontal. Children are element ids in order. Horizontal stacks use a single flex row so peers stay side-by-side and shrink with min-width 0. Nested stacks participate as flexible row peers. All-button horizontal stacks use an equal N-column grid where N is the number of buttons (1–6). Optional `columns` (`2`–`6`) forces an explicit equal grid for mixed children.",
+        "Layout container — direction: vertical (default) | horizontal. Children are element ids in order. Horizontal stacks use a single flex row so peers stay side-by-side and shrink with min-width 0. Nested stacks participate as flexible row peers. For all-button stacks, the @farcaster/snap React/React Native components choose row/column orientation from button label length, ignoring snap-sent direction hints; horizontal button rows use content-proportional widths while filling the container unless `equalWidth: true` is provided to force equal-width cells. Vertical button rows default to a tighter gap when `gap` is omitted.",
     },
     text: {
       props: textProps,
@@ -121,7 +121,8 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
       params: z.object({ target: z.string() }),
     },
     open_snap: {
-      description: "Open a snap URL inline. The client renders the target as a snap rather than opening a browser.",
+      description:
+        "Open a snap URL inline. The client renders the target as a snap rather than opening a browser.",
       params: z.object({ target: z.string() }),
     },
     open_mini_app: {

package/src/ui/cell-grid.ts

@@ -6,6 +6,7 @@ import {
   GRID_MIN_ROWS,
   GRID_MAX_ROWS,
   GRID_GAP_VALUES,
+  GRID_CELL_ASPECT_RATIO_VALUES,
 } from "../constants.js";
 
 /** Palette name or `#rrggbb`; input is trimmed so palette and hex rules match runtime resolvers. */
@@ -13,11 +14,9 @@ const cellGridCellColorSchema = z.preprocess(
   (v) => (typeof v === "string" ? v.trim() : v),
   z.union([
     z.enum(PALETTE_COLOR_VALUES),
-    z
-      .string()
-      .refine(isSnapHexColorString, {
-        message: "cell_grid cell hex color must be #rrggbb",
-      }),
+    z.string().refine(isSnapHexColorString, {
+      message: "cell_grid cell hex color must be #rrggbb",
+    }),
   ]),
 );
 
@@ -36,6 +35,7 @@ export const cellGridProps = z
     rows: z.number().int().min(GRID_MIN_ROWS).max(GRID_MAX_ROWS),
     cells: z.array(cellGridCellSchema),
     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(),
     select: z.enum(["off", "single", "multiple"]).optional(),
   })

package/src/ui/index.ts

@@ -16,8 +16,8 @@ export type { ToggleGroupProps } from "./toggle-group.js";
 export { inputProps } from "./input.js";
 export type { InputProps } from "./input.js";
 
-export { itemProps } from "./item.js";
-export type { ItemProps } from "./item.js";
+export { itemProps, itemMediaProps } from "./item.js";
+export type { ItemMediaProps, ItemProps } from "./item.js";
 
 export { itemGroupProps } from "./item-group.js";
 export type { ItemGroupProps } from "./item-group.js";

package/src/ui/item.ts

@@ -1,13 +1,43 @@
 import { z } from "zod";
+import { PROGRESS_COLOR_VALUES } from "../colors.js";
+import { ICON_NAMES } from "./icon.js";
 
 export const ITEM_VARIANTS = ["default"] as const;
+export const ITEM_MEDIA_VARIANTS = ["icon", "image"] as const;
 export const ITEM_MAX_TITLE_CHARS = 100;
 export const ITEM_MAX_DESCRIPTION_CHARS = 160;
+export const ITEM_MAX_MEDIA_ALT_CHARS = 120;
 
-export const itemProps = z.object({
-  title: z.string().min(1).max(ITEM_MAX_TITLE_CHARS),
-  description: z.string().max(ITEM_MAX_DESCRIPTION_CHARS).optional(),
-  variant: z.enum(ITEM_VARIANTS).optional(),
-});
+const itemIconMediaProps = z
+  .object({
+    variant: z.literal("icon"),
+    name: z.enum(ICON_NAMES),
+    color: z.enum(PROGRESS_COLOR_VALUES).optional(),
+  })
+  .strict();
+
+const itemImageMediaProps = z
+  .object({
+    variant: z.literal("image"),
+    url: z.string(),
+    alt: z.string().max(ITEM_MAX_MEDIA_ALT_CHARS).optional(),
+    round: z.boolean().optional(),
+  })
+  .strict();
+
+export const itemMediaProps = z.discriminatedUnion("variant", [
+  itemIconMediaProps,
+  itemImageMediaProps,
+]);
+
+export const itemProps = z
+  .object({
+    title: z.string().min(1).max(ITEM_MAX_TITLE_CHARS),
+    description: z.string().max(ITEM_MAX_DESCRIPTION_CHARS).optional(),
+    variant: z.enum(ITEM_VARIANTS).optional(),
+    media: itemMediaProps.optional(),
+  })
+  .strict();
 
 export type ItemProps = z.infer<typeof itemProps>;
+export type ItemMediaProps = z.infer<typeof itemMediaProps>;

package/src/ui/stack.ts

@@ -8,7 +8,9 @@ export const stackProps = z.object({
   direction: z.enum(STACK_DIRECTIONS).optional(),
   gap: z.enum(STACK_GAPS).optional(),
   justify: z.enum(STACK_JUSTIFY).optional(),
-  /** Horizontal stacks only: fixed column grid (`2`–`6`). Prefer omitting this when children are stacks — they flex as row peers automatically. */
+  /** Horizontal stacks only: make direct children equal width. */
+  equalWidth: z.boolean().optional(),
+  /** Horizontal stacks only: legacy fixed equal-width column count (`2`–`6`). Prefer `equalWidth`. */
   columns: z.union([
     z.literal(2),
     z.literal(3),

package/src/validator.ts

@@ -29,7 +29,12 @@ const URL_TARGET_ACTIONS = new Set([
  */
 function isLoopback(url: URL): boolean {
   const host = url.hostname;
-  return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]";
+  return (
+    host === "localhost" ||
+    host === "127.0.0.1" ||
+    host === "::1" ||
+    host === "[::1]"
+  );
 }
 
 /**
@@ -84,6 +89,11 @@ type ElementShape = {
   on?: Record<string, { action?: string; params?: Record<string, unknown> }>;
 };
 
+type ItemMediaShape = {
+  variant?: string;
+  url?: unknown;
+};
+
 // ─── Structural validation ────────────────────────────
 
 /**
@@ -169,6 +179,24 @@ function validateUrls(elements: Record<string, unknown>): z.core.$ZodIssue[] {
       }
     }
 
+    if (
+      el.type === "item" &&
+      el.props?.media &&
+      typeof el.props.media === "object"
+    ) {
+      const media = el.props.media as ItemMediaShape;
+      if (media.variant === "image" && typeof media.url === "string") {
+        const error = validateUrl(media.url);
+        if (error) {
+          issues.push({
+            code: "custom",
+            message: error,
+            path: ["ui", "elements", id, "props", "media", "url"],
+          });
+        }
+      }
+    }
+
     // Validate action target URLs
     if (el.on) {
       for (const [event, binding] of Object.entries(el.on)) {