@farcaster/snap 2.4.0 → 2.5.0

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

@@ -1,11 +1,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Children } from "react";
 import { StyleSheet, View } from "react-native";
-import { countRenderableChildren, defaultHorizontalGapSize, horizontalChildrenAreAllButtons, } from "../../stack-horizontal-utils.js";
+import { childrenShouldUseHorizontalButtonLayout, childrenAreAllButtons, countRenderableChildren, defaultHorizontalGapSize, } from "../../stack-horizontal-utils.js";
 import { SnapStackDirectionProvider, useSnapStackDirection, } from "../stack-direction-context.js";
 const VGAP = {
     none: 0,
-    sm: 8,
+    sm: 4,
     md: 16,
     lg: 24,
 };
@@ -22,62 +22,60 @@ const JUSTIFY = {
     between: "space-between",
     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) {
     const cells = Children.toArray(children).filter((c) => c != null && c !== false);
     return cells.map((child, i) => (_jsx(View, { style: styles.equalColumnCell, children: child }, i)));
 }
 export function SnapStack({ element: { props }, children, }) {
     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 &&
         columnsRaw <= 6 &&
         Number.isInteger(columnsRaw)
         ? 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)]
-                : VGAP.md;
-    const explicitColumnGrid = isHorizontal && columns !== undefined && !buttonRowGrid;
+            : allChildrenAreButtons
+                ? gapMap.sm
+                : isHorizontal
+                    ? gapMap[defaultHorizontalGapSize(horizontalChildCount)]
+                    : VGAP.md;
     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);
+    const packedHorizontal = isHorizontal && explicitEqualWidth;
     let horizontalBody = children;
-    if (isHorizontal &&
-        buttonRowGrid &&
-        buttonRowCount >= 1 &&
-        buttonRowCount <= 6) {
-        horizontalBody = wrapEqualColumnCells(children);
-    }
-    else if (isHorizontal && explicitColumnGrid && columns !== undefined) {
+    if (isHorizontal && explicitEqualWidth) {
         horizontalBody = wrapEqualColumnCells(children);
     }
     return (_jsx(SnapStackDirectionProvider, { direction: isHorizontal ? "horizontal" : "vertical", children: _jsx(View, { style: [
@@ -117,7 +115,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",
@@ -130,5 +128,6 @@ const styles = StyleSheet.create({
         flexShrink: 1,
         flexBasis: 0,
         minWidth: 0,
+        alignSelf: "stretch",
     },
 });

package/dist/react-native/components/snap-toggle-group.js

@@ -1,6 +1,7 @@
 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 { shouldUseHorizontalButtonContent } from "../../button-orientation-utils.js";
 import { useSnapTheme } from "../theme.js";
 export function SnapToggleGroup({ element: { props }, }) {
     const { get, set } = useStateStore();
@@ -9,7 +10,6 @@ export function SnapToggleGroup({ element: { props }, }) {
     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
         : [];
@@ -32,7 +32,7 @@ export function SnapToggleGroup({ element: { props }, }) {
         }
         return [];
     })();
-    const isVertical = orientation === "vertical";
+    const isVertical = !shouldUseHorizontalButtonContent(options);
     const handlePress = (opt) => {
         if (isMultiple) {
             const next = selected.includes(opt)
@@ -64,7 +64,7 @@ export function SnapToggleGroup({ element: { props }, }) {
                         ], onPress: () => handlePress(opt), children: _jsx(Text, { style: [
                                 styles.optionText,
                                 { color: colors.text },
-                            ], children: opt }) }, index));
+                            ], children: opt }) }, `${opt}-${index}`));
                 }) })] }));
 }
 const styles = StyleSheet.create({
@@ -89,7 +89,8 @@ const styles = StyleSheet.create({
         justifyContent: "center",
     },
     optionHorizontal: {
-        flex: 1,
+        flexGrow: 1,
+        flexShrink: 1,
     },
     optionText: {
         fontSize: 13,

package/dist/stack-horizontal-utils.d.ts

@@ -1,10 +1,12 @@
 import { type ReactNode } from "react";
-export declare function horizontalChildrenAreAllButtons(children: ReactNode): boolean;
-/** Direct snap catalog children under a stack (used for all-button grid column count). */
+export declare function childrenAreAllButtons(children: ReactNode): boolean;
+export declare function getButtonChildLabels(children: ReactNode): string[] | undefined;
+export declare function childrenShouldUseHorizontalButtonLayout(children: ReactNode): boolean | undefined;
+/** Direct snap catalog children under a stack (used for horizontal gap defaults). */
 export declare function countRenderableChildren(children: ReactNode): number;
 /**
- * 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 declare function defaultHorizontalGapSize(columnCount: number | undefined): "sm" | "md" | "lg";
+export declare function defaultHorizontalGapSize(childCount: number | undefined): "sm" | "md" | "lg";

package/dist/stack-horizontal-utils.js

@@ -1,4 +1,5 @@
 import { Children, isValidElement } 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,34 +11,43 @@ function isRenderableChild(c) {
         return false;
     return true;
 }
-export function horizontalChildrenAreAllButtons(children) {
+export function childrenAreAllButtons(children) {
+    return getButtonChildLabels(children) !== undefined;
+}
+export function getButtonChildLabels(children) {
     const items = Children.toArray(children).filter(isRenderableChild);
     if (items.length === 0)
-        return false;
+        return undefined;
+    const labels = [];
     for (const child of items) {
         if (!isValidElement(child))
-            return false;
-        const typ = child.props.element?.type;
-        if (typ !== "button")
-            return false;
+            return undefined;
+        const element = child.props.element;
+        if (element?.type !== "button")
+            return undefined;
+        labels.push(String(element.props?.label ?? ""));
     }
-    return true;
+    return labels;
+}
+export function childrenShouldUseHorizontalButtonLayout(children) {
+    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) {
     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) {
-    if (columnCount === undefined)
+export function defaultHorizontalGapSize(childCount) {
+    if (childCount === undefined)
         return "md";
-    if (columnCount <= 2)
+    if (childCount <= 2)
         return "lg";
-    if (columnCount === 3)
+    if (childCount === 3)
         return "md";
     return "sm";
 }

package/dist/ui/catalog.d.ts

@@ -186,7 +186,61 @@ export declare const snapJsonRenderCatalog: import("@json-render/core").Catalog<
                 variant: z.ZodOptional<z.ZodEnum<{
                     default: "default";
                 }>>;
-            }, z.core.$strip>;
+                media: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    variant: z.ZodLiteral<"icon">;
+                    name: z.ZodEnum<{
+                        "arrow-right": "arrow-right";
+                        "arrow-left": "arrow-left";
+                        "external-link": "external-link";
+                        "chevron-right": "chevron-right";
+                        check: "check";
+                        x: "x";
+                        "alert-triangle": "alert-triangle";
+                        info: "info";
+                        clock: "clock";
+                        heart: "heart";
+                        "message-circle": "message-circle";
+                        repeat: "repeat";
+                        share: "share";
+                        user: "user";
+                        users: "users";
+                        star: "star";
+                        trophy: "trophy";
+                        zap: "zap";
+                        flame: "flame";
+                        gift: "gift";
+                        image: "image";
+                        play: "play";
+                        pause: "pause";
+                        wallet: "wallet";
+                        coins: "coins";
+                        plus: "plus";
+                        minus: "minus";
+                        "refresh-cw": "refresh-cw";
+                        bookmark: "bookmark";
+                        "thumbs-up": "thumbs-up";
+                        "thumbs-down": "thumbs-down";
+                        "trending-up": "trending-up";
+                        "trending-down": "trending-down";
+                    }>;
+                    color: z.ZodOptional<z.ZodEnum<{
+                        gray: "gray";
+                        blue: "blue";
+                        red: "red";
+                        amber: "amber";
+                        green: "green";
+                        teal: "teal";
+                        purple: "purple";
+                        pink: "pink";
+                        accent: "accent";
+                    }>>;
+                }, z.core.$strict>, z.ZodObject<{
+                    variant: z.ZodLiteral<"image">;
+                    url: z.ZodString;
+                    alt: z.ZodOptional<z.ZodString>;
+                    round: z.ZodOptional<z.ZodBoolean>;
+                }, z.core.$strict>], "variant">>;
+            }, z.core.$strict>;
             description: string;
         };
         item_group: {
@@ -318,6 +372,7 @@ export declare const snapJsonRenderCatalog: import("@json-render/core").Catalog<
                     between: "between";
                     around: "around";
                 }>>;
+                equalWidth: z.ZodOptional<z.ZodBoolean>;
                 columns: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<5>, z.ZodLiteral<6>]>>;
             }, z.core.$strip>;
             description: string;
@@ -399,6 +454,10 @@ export declare const snapJsonRenderCatalog: import("@json-render/core").Catalog<
                     none: "none";
                     lg: "lg";
                 }>>;
+                cellAspectRatio: z.ZodOptional<z.ZodEnum<{
+                    auto: "auto";
+                    square: "square";
+                }>>;
                 rowHeight: z.ZodOptional<z.ZodNumber>;
                 select: z.ZodOptional<z.ZodEnum<{
                     multiple: "multiple";

package/dist/ui/catalog.js

@@ -42,7 +42,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.",
+            description: "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,
@@ -50,7 +50,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.",
+            description: "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,
@@ -78,7 +78,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.",
+            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. 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,

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

@@ -25,6 +25,10 @@ export declare const cellGridProps: z.ZodObject<{
         none: "none";
         lg: "lg";
     }>>;
+    cellAspectRatio: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        square: "square";
+    }>>;
     rowHeight: z.ZodOptional<z.ZodNumber>;
     select: z.ZodOptional<z.ZodEnum<{
         multiple: "multiple";

package/dist/ui/cell-grid.js

@@ -1,12 +1,10 @@
 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, } from "../constants.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";
 /** Palette name or `#rrggbb`; input is trimmed so palette and hex rules match runtime resolvers. */
 const cellGridCellColorSchema = z.preprocess((v) => (typeof v === "string" ? v.trim() : v), z.union([
     z.enum(PALETTE_COLOR_VALUES),
-    z
-        .string()
-        .refine(isSnapHexColorString, {
+    z.string().refine(isSnapHexColorString, {
         message: "cell_grid cell hex color must be #rrggbb",
     }),
 ]));
@@ -24,6 +22,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/dist/ui/index.d.ts

@@ -10,8 +10,8 @@ export { toggleGroupProps } from "./toggle-group.js";
 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";
 export { iconProps, ICON_NAMES } from "./icon.js";

package/dist/ui/index.js

@@ -5,7 +5,7 @@ export { buttonProps } from "./button.js";
 export { switchProps } from "./switch.js";
 export { toggleGroupProps } from "./toggle-group.js";
 export { inputProps } from "./input.js";
-export { itemProps } from "./item.js";
+export { itemProps, itemMediaProps } from "./item.js";
 export { itemGroupProps } from "./item-group.js";
 export { iconProps, ICON_NAMES } from "./icon.js";
 export { imageProps } from "./image.js";

package/dist/ui/item.d.ts

@@ -1,12 +1,123 @@
 import { z } from "zod";
 export declare const ITEM_VARIANTS: readonly ["default"];
+export declare const ITEM_MEDIA_VARIANTS: readonly ["icon", "image"];
 export declare const ITEM_MAX_TITLE_CHARS = 100;
 export declare const ITEM_MAX_DESCRIPTION_CHARS = 160;
+export declare const ITEM_MAX_MEDIA_ALT_CHARS = 120;
+export declare const itemMediaProps: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    variant: z.ZodLiteral<"icon">;
+    name: z.ZodEnum<{
+        "arrow-right": "arrow-right";
+        "arrow-left": "arrow-left";
+        "external-link": "external-link";
+        "chevron-right": "chevron-right";
+        check: "check";
+        x: "x";
+        "alert-triangle": "alert-triangle";
+        info: "info";
+        clock: "clock";
+        heart: "heart";
+        "message-circle": "message-circle";
+        repeat: "repeat";
+        share: "share";
+        user: "user";
+        users: "users";
+        star: "star";
+        trophy: "trophy";
+        zap: "zap";
+        flame: "flame";
+        gift: "gift";
+        image: "image";
+        play: "play";
+        pause: "pause";
+        wallet: "wallet";
+        coins: "coins";
+        plus: "plus";
+        minus: "minus";
+        "refresh-cw": "refresh-cw";
+        bookmark: "bookmark";
+        "thumbs-up": "thumbs-up";
+        "thumbs-down": "thumbs-down";
+        "trending-up": "trending-up";
+        "trending-down": "trending-down";
+    }>;
+    color: z.ZodOptional<z.ZodEnum<{
+        gray: "gray";
+        blue: "blue";
+        red: "red";
+        amber: "amber";
+        green: "green";
+        teal: "teal";
+        purple: "purple";
+        pink: "pink";
+        accent: "accent";
+    }>>;
+}, z.core.$strict>, z.ZodObject<{
+    variant: z.ZodLiteral<"image">;
+    url: z.ZodString;
+    alt: z.ZodOptional<z.ZodString>;
+    round: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>], "variant">;
 export declare const itemProps: z.ZodObject<{
     title: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     variant: z.ZodOptional<z.ZodEnum<{
         default: "default";
     }>>;
-}, z.core.$strip>;
+    media: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        variant: z.ZodLiteral<"icon">;
+        name: z.ZodEnum<{
+            "arrow-right": "arrow-right";
+            "arrow-left": "arrow-left";
+            "external-link": "external-link";
+            "chevron-right": "chevron-right";
+            check: "check";
+            x: "x";
+            "alert-triangle": "alert-triangle";
+            info: "info";
+            clock: "clock";
+            heart: "heart";
+            "message-circle": "message-circle";
+            repeat: "repeat";
+            share: "share";
+            user: "user";
+            users: "users";
+            star: "star";
+            trophy: "trophy";
+            zap: "zap";
+            flame: "flame";
+            gift: "gift";
+            image: "image";
+            play: "play";
+            pause: "pause";
+            wallet: "wallet";
+            coins: "coins";
+            plus: "plus";
+            minus: "minus";
+            "refresh-cw": "refresh-cw";
+            bookmark: "bookmark";
+            "thumbs-up": "thumbs-up";
+            "thumbs-down": "thumbs-down";
+            "trending-up": "trending-up";
+            "trending-down": "trending-down";
+        }>;
+        color: z.ZodOptional<z.ZodEnum<{
+            gray: "gray";
+            blue: "blue";
+            red: "red";
+            amber: "amber";
+            green: "green";
+            teal: "teal";
+            purple: "purple";
+            pink: "pink";
+            accent: "accent";
+        }>>;
+    }, z.core.$strict>, z.ZodObject<{
+        variant: z.ZodLiteral<"image">;
+        url: z.ZodString;
+        alt: z.ZodOptional<z.ZodString>;
+        round: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>], "variant">>;
+}, z.core.$strict>;
 export type ItemProps = z.infer<typeof itemProps>;
+export type ItemMediaProps = z.infer<typeof itemMediaProps>;

package/dist/ui/item.js

@@ -1,9 +1,35 @@
 import { z } from "zod";
+import { PROGRESS_COLOR_VALUES } from "../colors.js";
+import { ICON_NAMES } from "./icon.js";
 export const ITEM_VARIANTS = ["default"];
+export const ITEM_MEDIA_VARIANTS = ["icon", "image"];
 export const ITEM_MAX_TITLE_CHARS = 100;
 export const ITEM_MAX_DESCRIPTION_CHARS = 160;
-export const itemProps = z.object({
+export const ITEM_MAX_MEDIA_ALT_CHARS = 120;
+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();

package/dist/ui/stack.d.ts

@@ -20,6 +20,7 @@ export declare const stackProps: z.ZodObject<{
         between: "between";
         around: "around";
     }>>;
+    equalWidth: z.ZodOptional<z.ZodBoolean>;
     columns: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<5>, z.ZodLiteral<6>]>>;
 }, z.core.$strip>;
 export type StackProps = z.infer<typeof stackProps>;

package/dist/ui/stack.js

@@ -6,7 +6,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/dist/validator.js

@@ -14,7 +14,10 @@ const URL_TARGET_ACTIONS = new Set([
  */
 function isLoopback(url) {
     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]");
 }
 /**
  * Validate a URL string: must be HTTPS (or HTTP on loopback for dev).
@@ -124,6 +127,21 @@ function validateUrls(elements) {
                 });
             }
         }
+        if (el.type === "item" &&
+            el.props?.media &&
+            typeof el.props.media === "object") {
+            const media = el.props.media;
+            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)) {