@farcaster/snap 1.5.1 → 1.6.0

package/src/ui/badge.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { PROGRESS_COLOR_VALUES } from "../colors.js";
+import { ICON_NAMES } from "./icon.js";
+
+export const BADGE_MAX_LABEL_CHARS = 30;
+
+export const badgeProps = z.object({
+  label: z.string().min(1).max(BADGE_MAX_LABEL_CHARS),
+  color: z.enum(PROGRESS_COLOR_VALUES).optional(),
+  icon: z.enum(ICON_NAMES).optional(),
+});
+
+export type BadgeProps = z.infer<typeof badgeProps>;

package/src/ui/button.ts

@@ -1,16 +1,13 @@
 import { z } from "zod";
-import { BUTTON_ACTION_VALUES, BUTTON_STYLE_VALUES } from "../constants.js";
+import { ICON_NAMES } from "./icon.js";
 
-export const actionButtonProps = z.object({
-  label: z.string(),
-  action: z.enum(BUTTON_ACTION_VALUES),
-  target: z.string().optional(),
-  client_action: z.record(z.string(), z.unknown()).optional(),
-  style: z.enum(BUTTON_STYLE_VALUES).optional(),
-});
+export const BUTTON_VARIANTS = ["default", "secondary", "outline", "ghost"] as const;
+export const BUTTON_MAX_LABEL_CHARS = 30;
 
-export type ActionButtonProps = z.infer<typeof actionButtonProps>;
+export const buttonProps = z.object({
+  label: z.string().min(1).max(BUTTON_MAX_LABEL_CHARS),
+  variant: z.enum(BUTTON_VARIANTS).optional(),
+  icon: z.enum(ICON_NAMES).optional(),
+});
 
-/** Same schema as `actionButtonProps` (legacy export name). */
-export const buttonProps = actionButtonProps;
-export type ButtonProps = ActionButtonProps;
+export type ButtonProps = z.infer<typeof buttonProps>;

package/src/ui/catalog.ts

@@ -1,132 +1,152 @@
 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,
+    badge: {
+      props: badgeProps,
       description:
-        "Snap text block — style: title | body | caption | label; optional align.",
+        "Inline label — variant: default | secondary | destructive | outline.",
     },
-    Image: {
-      props: imageProps,
-      description: "HTTPS image with fixed aspect ratio.",
+    button: {
+      props: buttonProps,
+      description:
+        "Action button — use with on.press to bind snap or client actions.",
     },
-    Divider: {
-      props: dividerProps,
-      description: "Horizontal rule between blocks.",
+    switch: {
+      props: switchProps,
+      description:
+        "Boolean toggle; `name` becomes POST inputs key. Optional label.",
     },
-    Spacer: {
-      props: spacerProps,
-      description: "Vertical whitespace — size small | medium | large.",
+    toggle_group: {
+      props: toggleGroupProps,
+      description:
+        "Single or multi-select choice group; `name` becomes POST inputs key. mode: single (default) | multiple. Optional label.",
     },
-    Progress: {
-      props: progressProps,
+    input: {
+      props: inputProps,
       description:
-        "Horizontal progress bar (value/max, optional label and color).",
+        "Text input; `name` becomes POST inputs key. Optional label and placeholder.",
     },
-    List: {
-      props: listProps,
+    item: {
+      props: itemProps,
       description:
-        "Ordered / unordered / plain list; max 4 items per snap spec.",
+        "Content row with title and optional description. Children render in the actions slot (right side) — use badge, button, or text elements.",
     },
-    Grid: {
-      props: gridProps,
+    item_group: {
+      props: itemGroupProps,
       description:
-        "Rows×cols cell grid; optional interactive empty cells for games.",
+        "Groups item children into a styled list. Optional border around the group and separator lines between items.",
     },
-    TextInput: {
-      props: textInputProps,
-      description: "Single-line input; `name` becomes POST inputs key.",
+    icon: {
+      props: iconProps,
+      description:
+        "Inline icon from the curated set. Optional color (palette) and size (sm | md).",
     },
-    Slider: {
-      props: sliderProps,
-      description: "Numeric slider; `name` becomes POST inputs key.",
+    image: {
+      props: imageProps,
+      description: "HTTPS image with fixed aspect ratio.",
     },
-    ButtonGroup: {
-      props: buttonGroupProps,
+    progress: {
+      props: progressProps,
       description:
-        "Exclusive choice; `name` and selected option go into POST inputs.",
-    },
-    Toggle: {
-      props: toggleProps,
-      description: "Boolean toggle; `name` becomes POST inputs key.",
+        "Horizontal progress bar (value/max, optional label and color).",
     },
-    BarChart: {
-      props: barChartProps,
+    separator: {
+      props: separatorProps,
       description:
-        "Vertical bar chart for labeled values — poll results, rankings, breakdowns.",
+        "Visual divider — orientation: horizontal (default) | vertical.",
     },
-    Group: {
-      props: groupProps,
+    slider: {
+      props: sliderProps,
       description:
-        "Button row (`layout: row`) or 2-column grid (`layout: grid`); use `children` element ids only (no nested JSON objects).",
+        "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.",
+        "Layout container — direction: vertical (default) | horizontal. Children are element ids in order.",
     },
-    ActionButton: {
-      props: actionButtonProps,
+    text: {
+      props: textProps,
       description:
-        "Snap action button: post (next page), link (browser), mini_app, client — target is HTTPS URL or client_action object.",
+        "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: {
+    submit: {
       description:
-        "Trigger a Farcaster client action (view_cast, view_profile, compose_cast, …).",
-      params: snapClientParams,
+        "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/src/ui/icon.ts

@@ -0,0 +1,56 @@
+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",
+] as const;
+
+export const ICON_SIZES = ["sm", "md"] as const;
+
+export const iconProps = z.object({
+  name: z.enum(ICON_NAMES),
+  color: z.enum(PROGRESS_COLOR_VALUES).optional(),
+  size: z.enum(ICON_SIZES).optional(),
+});
+
+export type IconProps = z.infer<typeof iconProps>;

package/src/ui/image.ts

@@ -1,9 +1,10 @@
 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"] as const;
 
 export const imageProps = z.object({
   url: z.string(),
-  aspect: z.enum(IMAGE_ASPECT_VALUES),
+  aspect: z.enum(IMAGE_ASPECTS),
   alt: z.string().optional(),
 });
 

package/src/ui/index.ts

@@ -1,47 +1,44 @@
 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 { imageProps } from "./image.js";
-export type { ImageProps } from "./image.js";
+export { buttonProps } from "./button.js";
+export type { ButtonProps } from "./button.js";
 
-export { dividerProps } from "./divider.js";
-export type { DividerProps } from "./divider.js";
+export { switchProps } from "./switch.js";
+export type { SwitchProps } from "./switch.js";
 
-export { spacerProps } from "./spacer.js";
-export type { SpacerProps } from "./spacer.js";
+export { toggleGroupProps } from "./toggle-group.js";
+export type { ToggleGroupProps } from "./toggle-group.js";
 
-export { progressProps } from "./progress.js";
-export type { ProgressProps } from "./progress.js";
-
-export { listProps } from "./list.js";
-export type { ListProps } from "./list.js";
+export { inputProps } from "./input.js";
+export type { InputProps } from "./input.js";
 
-export { gridProps } from "./grid.js";
-export type { GridProps } from "./grid.js";
+export { itemProps } from "./item.js";
+export type { ItemProps } from "./item.js";
 
-export { textInputProps } from "./text-input.js";
-export type { TextInputProps } from "./text-input.js";
+export { itemGroupProps } from "./item-group.js";
+export type { ItemGroupProps } from "./item-group.js";
 
-export { sliderProps } from "./slider.js";
-export type { SliderProps } from "./slider.js";
+export { iconProps, ICON_NAMES } from "./icon.js";
+export type { IconProps } from "./icon.js";
 
-export { buttonGroupProps } from "./button-group.js";
-export type { ButtonGroupProps } from "./button-group.js";
+export { imageProps } from "./image.js";
+export type { ImageProps } from "./image.js";
 
-export { toggleProps } from "./toggle.js";
-export type { ToggleProps } from "./toggle.js";
+export { progressProps } from "./progress.js";
+export type { ProgressProps } from "./progress.js";
 
-export { barChartProps } from "./bar-chart.js";
-export type { BarChartProps } from "./bar-chart.js";
+export { separatorProps } from "./separator.js";
+export type { SeparatorProps } from "./separator.js";
 
-export { groupProps } from "./group.js";
-export type { GroupProps } from "./group.js";
+export { sliderProps } from "./slider.js";
+export type { SliderProps } from "./slider.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/src/ui/input.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+
+export const INPUT_TYPES = ["text", "number"] as const;
+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(),
+});
+
+export type InputProps = z.infer<typeof inputProps>;

package/src/ui/item-group.ts

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

package/src/ui/item.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+
+export const ITEM_VARIANTS = ["default", "outline", "muted"] as const;
+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(),
+});
+
+export type ItemProps = z.infer<typeof itemProps>;

package/src/ui/progress.ts

@@ -1,11 +1,29 @@
 import { z } from "zod";
-import { PROGRESS_COLOR_VALUES } from "../colors.js";
 
-export const progressProps = z.object({
-  value: z.number(),
-  max: z.number(),
-  label: z.string().optional(),
-  color: z.enum(PROGRESS_COLOR_VALUES).optional(),
-});
+export const PROGRESS_MAX_LABEL_CHARS = 60;
+
+export const progressProps = z
+  .object({
+    value: z.number(),
+    max: z.number(),
+    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"],
+      });
+    }
+  });
 
 export type ProgressProps = z.infer<typeof progressProps>;

package/src/ui/schema.ts

@@ -29,9 +29,9 @@ export const snapJsonRenderSchema = defineSchema(
   }),
   {
     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/src/ui/separator.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export const SEPARATOR_ORIENTATIONS = ["horizontal", "vertical"] as const;
+
+export const separatorProps = z.object({
+  orientation: z.enum(SEPARATOR_ORIENTATIONS).optional(),
+});
+
+export type SeparatorProps = z.infer<typeof separatorProps>;

package/src/ui/slider.ts

@@ -1,14 +1,44 @@
 import { z } from "zod";
 
-export const sliderProps = z.object({
-  name: z.string().min(1),
-  min: z.number(),
-  max: z.number(),
-  step: z.number().optional(),
-  value: z.number().optional(),
-  label: z.string().optional(),
-  minLabel: z.string().optional(),
-  maxLabel: z.string().optional(),
-});
+export const SLIDER_MAX_LABEL_CHARS = 60;
+export const SLIDER_DEFAULT_STEP = 1;
+export const SLIDER_STEP_ALIGN_EPS = 1e-6;
+
+export const sliderProps = z
+  .object({
+    name: z.string().min(1),
+    min: z.number(),
+    max: z.number(),
+    step: z.number().optional(),
+    defaultValue: z.number().optional(),
+    label: z.string().max(SLIDER_MAX_LABEL_CHARS).optional(),
+  })
+  .superRefine((val, ctx) => {
+    if (val.min > val.max) {
+      ctx.addIssue({
+        code: "custom",
+        message: `slider min (${val.min}) must be <= max (${val.max})`,
+        path: ["min"],
+      });
+      return;
+    }
+    if (val.step !== undefined && (val.step <= 0 || !Number.isFinite(val.step))) {
+      ctx.addIssue({
+        code: "custom",
+        message: "slider step must be a finite number > 0",
+        path: ["step"],
+      });
+      return;
+    }
+    if (val.defaultValue !== undefined) {
+      if (val.defaultValue < val.min || val.defaultValue > val.max) {
+        ctx.addIssue({
+          code: "custom",
+          message: `slider defaultValue (${val.defaultValue}) must be between min (${val.min}) and max (${val.max})`,
+          path: ["defaultValue"],
+        });
+      }
+    }
+  });
 
 export type SliderProps = z.infer<typeof sliderProps>;

package/src/ui/stack.ts

@@ -1,5 +1,13 @@
 import { z } from "zod";
 
-export const stackProps = z.object({});
+export const STACK_DIRECTIONS = ["vertical", "horizontal"] as const;
+export const STACK_GAPS = ["none", "sm", "md", "lg"] as const;
+export const STACK_JUSTIFY = ["start", "center", "end", "between", "around"] as const;
+
+export const stackProps = z.object({
+  direction: z.enum(STACK_DIRECTIONS).optional(),
+  gap: z.enum(STACK_GAPS).optional(),
+  justify: z.enum(STACK_JUSTIFY).optional(),
+});
 
 export type StackProps = z.infer<typeof stackProps>;

package/src/ui/switch.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+
+export const SWITCH_MAX_LABEL_CHARS = 60;
+
+export const switchProps = z.object({
+  name: z.string().min(1),
+  label: z.string().max(SWITCH_MAX_LABEL_CHARS).optional(),
+  defaultChecked: z.boolean().optional(),
+});
+
+export type SwitchProps = z.infer<typeof switchProps>;

package/src/ui/text.ts

@@ -1,10 +1,15 @@
 import { z } from "zod";
-import { TEXT_ALIGN_VALUES, TEXT_STYLE_VALUES } from "../constants.js";
+
+export const TEXT_SIZES = ["lg", "md", "sm"] as const;
+export const TEXT_WEIGHTS = ["bold", "medium", "normal"] as const;
+export const TEXT_ALIGNS = ["left", "center", "right"] as const;
+export const TEXT_MAX_CONTENT_CHARS = 320;
 
 export const textProps = z.object({
-  style: z.enum(TEXT_STYLE_VALUES),
-  content: z.string(),
-  align: z.enum(TEXT_ALIGN_VALUES).optional(),
+  content: z.string().min(1).max(TEXT_MAX_CONTENT_CHARS),
+  size: z.enum(TEXT_SIZES).optional(),
+  weight: z.enum(TEXT_WEIGHTS).optional(),
+  align: z.enum(TEXT_ALIGNS).optional(),
 });
 
 export type TextProps = z.infer<typeof textProps>;