@farcaster/snap 1.5.1 → 2.0.0

package/dist/ui/catalog.js

@@ -1,117 +1,136 @@
 import { defineCatalog } from "@json-render/core";
 import { z } from "zod";
-import { BUTTON_STYLE_VALUES } from "../constants.js";
 import { snapJsonRenderSchema } from "./schema.js";
-import { textProps } from "./text.js";
+import { badgeProps } from "./badge.js";
+import { buttonProps } from "./button.js";
+import { switchProps } from "./switch.js";
+import { toggleGroupProps } from "./toggle-group.js";
+import { iconProps } from "./icon.js";
+import { inputProps } from "./input.js";
+import { itemProps } from "./item.js";
+import { itemGroupProps } from "./item-group.js";
 import { imageProps } from "./image.js";
-import { dividerProps } from "./divider.js";
-import { spacerProps } from "./spacer.js";
 import { progressProps } from "./progress.js";
-import { listProps } from "./list.js";
-import { gridProps } from "./grid.js";
-import { textInputProps } from "./text-input.js";
+import { separatorProps } from "./separator.js";
 import { sliderProps } from "./slider.js";
-import { buttonGroupProps } from "./button-group.js";
-import { toggleProps } from "./toggle.js";
-import { barChartProps } from "./bar-chart.js";
-import { groupProps } from "./group.js";
 import { stackProps } from "./stack.js";
-import { actionButtonProps } from "./button.js";
-const snapPostParams = z.object({
-    button_index: z.number().int().nonnegative(),
-    target: z.string(),
-    label: z.string().optional(),
-    style: z.enum(BUTTON_STYLE_VALUES).optional(),
-});
-const snapTargetParams = z.object({
-    target: z.string(),
-});
+import { textProps } from "./text.js";
 const snapClientParams = z.object({
     client_action: z.record(z.string(), z.unknown()),
 });
 /**
- * Basic catalog: one json-render component per snap element type, plus ActionButton for snap buttons.
- * Does not validate cross-field rules (media count, height budget); snap JSON still goes through `@farcaster/snap` validation.
+ * json-render catalog for snap elements.
+ *
+ * Component keys match the snap wire-format `type` strings.
+ * Action names are used directly in `on.press` bindings.
  */
 export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
     components: {
-        Text: {
-            props: textProps,
-            description: "Snap text block — style: title | body | caption | label; optional align.",
+        badge: {
+            props: badgeProps,
+            description: "Inline label — variant: default | secondary | destructive | outline.",
         },
-        Image: {
-            props: imageProps,
-            description: "HTTPS image with fixed aspect ratio.",
-        },
-        Divider: {
-            props: dividerProps,
-            description: "Horizontal rule between blocks.",
+        button: {
+            props: buttonProps,
+            description: "Action button — use with on.press to bind snap or client actions.",
         },
-        Spacer: {
-            props: spacerProps,
-            description: "Vertical whitespace — size small | medium | large.",
+        switch: {
+            props: switchProps,
+            description: "Boolean toggle; `name` becomes POST inputs key. Optional label.",
         },
-        Progress: {
-            props: progressProps,
-            description: "Horizontal progress bar (value/max, optional label and color).",
+        toggle_group: {
+            props: toggleGroupProps,
+            description: "Single or multi-select choice group; `name` becomes POST inputs key. mode: single (default) | multiple. Optional label.",
         },
-        List: {
-            props: listProps,
-            description: "Ordered / unordered / plain list; max 4 items per snap spec.",
+        input: {
+            props: inputProps,
+            description: "Text input; `name` becomes POST inputs key. Optional label and placeholder.",
         },
-        Grid: {
-            props: gridProps,
-            description: "Rows×cols cell grid; optional interactive empty cells for games.",
+        item: {
+            props: itemProps,
+            description: "Content row with title and optional description. Children render in the actions slot (right side) — use badge, button, or text elements.",
         },
-        TextInput: {
-            props: textInputProps,
-            description: "Single-line input; `name` becomes POST inputs key.",
+        item_group: {
+            props: itemGroupProps,
+            description: "Groups item children into a styled list. Optional border around the group and separator lines between items.",
         },
-        Slider: {
-            props: sliderProps,
-            description: "Numeric slider; `name` becomes POST inputs key.",
+        icon: {
+            props: iconProps,
+            description: "Inline icon from the curated set. Optional color (palette) and size (sm | md).",
         },
-        ButtonGroup: {
-            props: buttonGroupProps,
-            description: "Exclusive choice; `name` and selected option go into POST inputs.",
+        image: {
+            props: imageProps,
+            description: "HTTPS image with fixed aspect ratio.",
         },
-        Toggle: {
-            props: toggleProps,
-            description: "Boolean toggle; `name` becomes POST inputs key.",
+        progress: {
+            props: progressProps,
+            description: "Horizontal progress bar (value/max, optional label and color).",
         },
-        BarChart: {
-            props: barChartProps,
-            description: "Vertical bar chart for labeled values — poll results, rankings, breakdowns.",
+        separator: {
+            props: separatorProps,
+            description: "Visual divider — orientation: horizontal (default) | vertical.",
         },
-        Group: {
-            props: groupProps,
-            description: "Button row (`layout: row`) or 2-column grid (`layout: grid`); use `children` element ids only (no nested JSON objects).",
+        slider: {
+            props: sliderProps,
+            description: "Numeric slider; `name` becomes POST inputs key. Optional label.",
         },
-        Stack: {
+        stack: {
             props: stackProps,
-            description: "Vertical stack for snap page body; maps from snap `page.elements` (`type: stack`). Children are element ids in order top to bottom.",
+            description: "Layout container — direction: vertical (default) | horizontal. Children are element ids in order.",
         },
-        ActionButton: {
-            props: actionButtonProps,
-            description: "Snap action button: post (next page), link (browser), mini_app, client — target is HTTPS URL or client_action object.",
+        text: {
+            props: textProps,
+            description: "Text block — size: lg (heading), md (body, default), sm (caption). Optional weight and align.",
         },
     },
     actions: {
-        snap_post: {
-            description: "POST to snap `target` with signed body (fid, inputs, button_index, timestamp, signature); response is next snap page JSON.",
-            params: snapPostParams,
-        },
-        snap_link: {
-            description: "Open `target` in the system browser; no server round-trip.",
-            params: snapTargetParams,
-        },
-        snap_mini_app: {
-            description: "Open `target` as an in-app Farcaster mini app.",
-            params: snapTargetParams,
-        },
-        snap_client: {
-            description: "Trigger a Farcaster client action (view_cast, view_profile, compose_cast, …).",
-            params: snapClientParams,
+        submit: {
+            description: "POST to snap server with signed body (fid, inputs, timestamp, signature); response is next snap page.",
+            params: z.object({ target: z.string() }),
+        },
+        open_url: {
+            description: "Open target URL in the system browser.",
+            params: z.object({ target: z.string() }),
+        },
+        open_mini_app: {
+            description: "Open target URL as a Farcaster mini app.",
+            params: z.object({ target: z.string() }),
+        },
+        view_cast: {
+            description: "Navigate to a cast by hash.",
+            params: z.object({ hash: z.string() }),
+        },
+        view_profile: {
+            description: "Navigate to a user profile by FID.",
+            params: z.object({ fid: z.number() }),
+        },
+        compose_cast: {
+            description: "Open the cast composer with optional pre-filled content.",
+            params: z.object({
+                text: z.string().optional(),
+                channelKey: z.string().optional(),
+                embeds: z.array(z.string()).optional(),
+            }),
+        },
+        view_token: {
+            description: "View a token in the wallet. Token is a CAIP-19 identifier.",
+            params: z.object({ token: z.string() }),
+        },
+        send_token: {
+            description: "Open send flow for a token. Token is CAIP-19.",
+            params: z.object({
+                token: z.string(),
+                amount: z.string().optional(),
+                recipientFid: z.number().optional(),
+                recipientAddress: z.string().optional(),
+            }),
+        },
+        swap_token: {
+            description: "Open swap flow between two tokens. Tokens are CAIP-19.",
+            params: z.object({
+                sellToken: z.string().optional(),
+                buyToken: z.string().optional(),
+            }),
         },
     },
 });

package/dist/ui/icon.d.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+export declare const ICON_NAMES: readonly ["arrow-right", "arrow-left", "external-link", "chevron-right", "check", "x", "alert-triangle", "info", "clock", "heart", "message-circle", "repeat", "share", "user", "users", "star", "trophy", "zap", "flame", "gift", "image", "play", "pause", "wallet", "coins", "plus", "minus", "refresh-cw", "bookmark", "thumbs-up", "thumbs-down", "trending-up", "trending-down"];
+export declare const ICON_SIZES: readonly ["sm", "md"];
+export declare const iconProps: z.ZodObject<{
+    name: z.ZodEnum<{
+        check: "check";
+        repeat: "repeat";
+        "arrow-right": "arrow-right";
+        "arrow-left": "arrow-left";
+        "external-link": "external-link";
+        "chevron-right": "chevron-right";
+        x: "x";
+        "alert-triangle": "alert-triangle";
+        info: "info";
+        clock: "clock";
+        heart: "heart";
+        "message-circle": "message-circle";
+        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";
+    }>>;
+    size: z.ZodOptional<z.ZodEnum<{
+        sm: "sm";
+        md: "md";
+    }>>;
+}, z.core.$strip>;
+export type IconProps = z.infer<typeof iconProps>;

package/dist/ui/icon.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { PROGRESS_COLOR_VALUES } from "../colors.js";
+export const ICON_NAMES = [
+    // Navigation/Actions
+    "arrow-right",
+    "arrow-left",
+    "external-link",
+    "chevron-right",
+    // Status
+    "check",
+    "x",
+    "alert-triangle",
+    "info",
+    "clock",
+    // Social
+    "heart",
+    "message-circle",
+    "repeat",
+    "share",
+    "user",
+    "users",
+    // Content
+    "star",
+    "trophy",
+    "zap",
+    "flame",
+    "gift",
+    // Media
+    "image",
+    "play",
+    "pause",
+    // Commerce
+    "wallet",
+    "coins",
+    // Common actions
+    "plus",
+    "minus",
+    "refresh-cw",
+    "bookmark",
+    // Feedback/data
+    "thumbs-up",
+    "thumbs-down",
+    "trending-up",
+    "trending-down",
+];
+export const ICON_SIZES = ["sm", "md"];
+export const iconProps = z.object({
+    name: z.enum(ICON_NAMES),
+    color: z.enum(PROGRESS_COLOR_VALUES).optional(),
+    size: z.enum(ICON_SIZES).optional(),
+});

package/dist/ui/image.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+export declare const IMAGE_ASPECTS: readonly ["1:1", "16:9", "4:3", "3:4", "9:16"];
 export declare const imageProps: z.ZodObject<{
     url: z.ZodString;
     aspect: z.ZodEnum<{

package/dist/ui/image.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { IMAGE_ASPECT_VALUES } from "../constants.js";
+export const IMAGE_ASPECTS = ["1:1", "16:9", "4:3", "3:4", "9:16"];
 export const imageProps = z.object({
     url: z.string(),
-    aspect: z.enum(IMAGE_ASPECT_VALUES),
+    aspect: z.enum(IMAGE_ASPECTS),
     alt: z.string().optional(),
 });

package/dist/ui/index.d.ts

@@ -1,32 +1,30 @@
 export { snapJsonRenderSchema } from "./schema.js";
 export { snapJsonRenderCatalog } from "./catalog.js";
-export { textProps } from "./text.js";
-export type { TextProps } from "./text.js";
+export { badgeProps } from "./badge.js";
+export type { BadgeProps } from "./badge.js";
+export { buttonProps } from "./button.js";
+export type { ButtonProps } from "./button.js";
+export { switchProps } from "./switch.js";
+export type { SwitchProps } from "./switch.js";
+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 { itemGroupProps } from "./item-group.js";
+export type { ItemGroupProps } from "./item-group.js";
+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 { dividerProps } from "./divider.js";
-export type { DividerProps } from "./divider.js";
-export { spacerProps } from "./spacer.js";
-export type { SpacerProps } from "./spacer.js";
 export { progressProps } from "./progress.js";
 export type { ProgressProps } from "./progress.js";
-export { listProps } from "./list.js";
-export type { ListProps } from "./list.js";
-export { gridProps } from "./grid.js";
-export type { GridProps } from "./grid.js";
-export { textInputProps } from "./text-input.js";
-export type { TextInputProps } from "./text-input.js";
+export { separatorProps } from "./separator.js";
+export type { SeparatorProps } from "./separator.js";
 export { sliderProps } from "./slider.js";
 export type { SliderProps } from "./slider.js";
-export { buttonGroupProps } from "./button-group.js";
-export type { ButtonGroupProps } from "./button-group.js";
-export { toggleProps } from "./toggle.js";
-export type { ToggleProps } from "./toggle.js";
-export { barChartProps } from "./bar-chart.js";
-export type { BarChartProps } from "./bar-chart.js";
-export { groupProps } from "./group.js";
-export type { GroupProps } from "./group.js";
 export { stackProps } from "./stack.js";
 export type { StackProps } from "./stack.js";
-export { actionButtonProps, buttonProps } from "./button.js";
-export type { ActionButtonProps, ButtonProps } from "./button.js";
+export { textProps } from "./text.js";
+export type { TextProps } from "./text.js";

package/dist/ui/index.js

@@ -1,17 +1,16 @@
 export { snapJsonRenderSchema } from "./schema.js";
 export { snapJsonRenderCatalog } from "./catalog.js";
-export { textProps } from "./text.js";
+export { badgeProps } from "./badge.js";
+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 { itemGroupProps } from "./item-group.js";
+export { iconProps, ICON_NAMES } from "./icon.js";
 export { imageProps } from "./image.js";
-export { dividerProps } from "./divider.js";
-export { spacerProps } from "./spacer.js";
 export { progressProps } from "./progress.js";
-export { listProps } from "./list.js";
-export { gridProps } from "./grid.js";
-export { textInputProps } from "./text-input.js";
+export { separatorProps } from "./separator.js";
 export { sliderProps } from "./slider.js";
-export { buttonGroupProps } from "./button-group.js";
-export { toggleProps } from "./toggle.js";
-export { barChartProps } from "./bar-chart.js";
-export { groupProps } from "./group.js";
 export { stackProps } from "./stack.js";
-export { actionButtonProps, buttonProps } from "./button.js";
+export { textProps } from "./text.js";

package/dist/ui/input.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+export declare const INPUT_TYPES: readonly ["text", "number"];
+export declare const INPUT_MAX_CHARS = 280;
+export declare const INPUT_MAX_LABEL_CHARS = 60;
+export declare const INPUT_MAX_PLACEHOLDER_CHARS = 60;
+export declare const inputProps: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodOptional<z.ZodEnum<{
+        number: "number";
+        text: "text";
+    }>>;
+    label: z.ZodOptional<z.ZodString>;
+    placeholder: z.ZodOptional<z.ZodString>;
+    defaultValue: z.ZodOptional<z.ZodString>;
+    maxLength: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type InputProps = z.infer<typeof inputProps>;

package/dist/ui/input.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+export const INPUT_TYPES = ["text", "number"];
+export const INPUT_MAX_CHARS = 280;
+export const INPUT_MAX_LABEL_CHARS = 60;
+export const INPUT_MAX_PLACEHOLDER_CHARS = 60;
+export const inputProps = z.object({
+    name: z.string().min(1),
+    type: z.enum(INPUT_TYPES).optional(),
+    label: z.string().max(INPUT_MAX_LABEL_CHARS).optional(),
+    placeholder: z.string().max(INPUT_MAX_PLACEHOLDER_CHARS).optional(),
+    defaultValue: z.string().optional(),
+    maxLength: z.number().int().min(1).max(INPUT_MAX_CHARS).optional(),
+});

package/dist/ui/item-group.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+export declare const itemGroupProps: z.ZodObject<{
+    border: z.ZodOptional<z.ZodBoolean>;
+    separator: z.ZodOptional<z.ZodBoolean>;
+    gap: z.ZodOptional<z.ZodEnum<{
+        sm: "sm";
+        md: "md";
+        none: "none";
+        lg: "lg";
+    }>>;
+}, z.core.$strip>;
+export type ItemGroupProps = z.infer<typeof itemGroupProps>;

package/dist/ui/item-group.js

@@ -0,0 +1,7 @@
+import { z } from "zod";
+import { STACK_GAPS } from "./stack.js";
+export const itemGroupProps = z.object({
+    border: z.boolean().optional(),
+    separator: z.boolean().optional(),
+    gap: z.enum(STACK_GAPS).optional(),
+});

package/dist/ui/item.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+export declare const ITEM_VARIANTS: readonly ["default", "outline", "muted"];
+export declare const ITEM_MAX_TITLE_CHARS = 100;
+export declare const ITEM_MAX_DESCRIPTION_CHARS = 160;
+export declare const itemProps: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    variant: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        outline: "outline";
+        muted: "muted";
+    }>>;
+}, z.core.$strip>;
+export type ItemProps = z.infer<typeof itemProps>;

package/dist/ui/item.js

@@ -0,0 +1,9 @@
+import { z } from "zod";
+export const ITEM_VARIANTS = ["default", "outline", "muted"];
+export const ITEM_MAX_TITLE_CHARS = 100;
+export const ITEM_MAX_DESCRIPTION_CHARS = 160;
+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(),
+});

package/dist/ui/progress.d.ts

@@ -1,18 +1,8 @@
 import { z } from "zod";
+export declare const PROGRESS_MAX_LABEL_CHARS = 60;
 export declare const progressProps: z.ZodObject<{
     value: z.ZodNumber;
     max: z.ZodNumber;
     label: z.ZodOptional<z.ZodString>;
-    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.$strip>;
 export type ProgressProps = z.infer<typeof progressProps>;

package/dist/ui/progress.js

@@ -1,8 +1,25 @@
 import { z } from "zod";
-import { PROGRESS_COLOR_VALUES } from "../colors.js";
-export const progressProps = z.object({
+export const PROGRESS_MAX_LABEL_CHARS = 60;
+export const progressProps = z
+    .object({
     value: z.number(),
     max: z.number(),
-    label: z.string().optional(),
-    color: z.enum(PROGRESS_COLOR_VALUES).optional(),
+    label: z.string().max(PROGRESS_MAX_LABEL_CHARS).optional(),
+})
+    .superRefine((val, ctx) => {
+    if (!Number.isFinite(val.max) || val.max <= 0) {
+        ctx.addIssue({
+            code: "custom",
+            message: `progress max must be a finite number > 0 (got ${val.max})`,
+            path: ["max"],
+        });
+        return;
+    }
+    if (!Number.isFinite(val.value) || val.value < 0 || val.value > val.max) {
+        ctx.addIssue({
+            code: "custom",
+            message: `progress value (${val.value}) must be between 0 and max (${val.max})`,
+            path: ["value"],
+        });
+    }
 });

package/dist/ui/schema.js

@@ -24,8 +24,8 @@ export const snapJsonRenderSchema = defineSchema((s) => ({
     }),
 }), {
     defaultRules: [
-        "You are generating auxiliary UI for a Farcaster Snap. Prefer components matching snap element types (Text, Image, ButtonGroup, …).",
-        "Snap pages use a Stack root with at most 5 body children and 1 media element (Image or Grid); keep generated trees small.",
-        "Bottom-of-card snap buttons are ActionButton components; use actions post / link / mini_app / client.",
+        "You are generating auxiliary UI for a Farcaster Snap. Prefer components matching snap element types (Item, Badge, ButtonGroup, Input, Switch, ToggleGroup, Slider, Progress, Image, Separator).",
+        "Snap pages use a Stack root with at most 6 body children and 1 media element (Image); keep generated trees small.",
+        "Bottom-of-card snap buttons are Button components; use actions post / link / mini_app / sdk per SPEC.md.",
     ],
 });

package/dist/ui/separator.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+export declare const SEPARATOR_ORIENTATIONS: readonly ["horizontal", "vertical"];
+export declare const separatorProps: z.ZodObject<{
+    orientation: z.ZodOptional<z.ZodEnum<{
+        horizontal: "horizontal";
+        vertical: "vertical";
+    }>>;
+}, z.core.$strip>;
+export type SeparatorProps = z.infer<typeof separatorProps>;

package/dist/ui/separator.js

@@ -0,0 +1,5 @@
+import { z } from "zod";
+export const SEPARATOR_ORIENTATIONS = ["horizontal", "vertical"];
+export const separatorProps = z.object({
+    orientation: z.enum(SEPARATOR_ORIENTATIONS).optional(),
+});

package/dist/ui/slider.d.ts

@@ -1,12 +1,13 @@
 import { z } from "zod";
+export declare const SLIDER_MAX_LABEL_CHARS = 60;
+export declare const SLIDER_DEFAULT_STEP = 1;
+export declare const SLIDER_STEP_ALIGN_EPS = 0.000001;
 export declare const sliderProps: z.ZodObject<{
     name: z.ZodString;
     min: z.ZodNumber;
     max: z.ZodNumber;
     step: z.ZodOptional<z.ZodNumber>;
-    value: z.ZodOptional<z.ZodNumber>;
+    defaultValue: z.ZodOptional<z.ZodNumber>;
     label: z.ZodOptional<z.ZodString>;
-    minLabel: z.ZodOptional<z.ZodString>;
-    maxLabel: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type SliderProps = z.infer<typeof sliderProps>;