@farcaster/snap 1.3.0 → 1.3.2

package/src/schemas.ts

@@ -1,4 +1,4 @@
-import { z } from "zod/v4";
+import { z } from "zod";
 import {
   BAR_CHART_COLOR_VALUES,
   BUTTON_ACTION,
@@ -35,7 +35,6 @@ import {
   TEXT_CONTENT_MAX,
   TEXT_STYLE,
   TEXT_STYLE_VALUES,
-  VIDEO_ASPECT_VALUES,
 } from "./constants";
 
 /**
@@ -94,13 +93,6 @@ const imageUrlSchema = z
       "image URL must use HTTPS and end with a supported extension (.jpg, .png, .gif, .webp)",
   });
 
-const videoUrlSchema = z
-  .string()
-  .refine((s) => hasAllowedMediaExtension(s, ["mp4", "webm"]), {
-    message:
-      "video URL must use HTTPS and end with a supported extension (.mp4, .webm)",
-  });
-
 const textAlignSchema = z.enum(TEXT_ALIGN_VALUES);
 
 const textElementSchema = z
@@ -128,14 +120,6 @@ const imageElementSchema = z.object({
   alt: z.string().optional(),
 });
 
-const videoElementSchema = z.object({
-  type: z.literal(ELEMENT_TYPE.video),
-  url: videoUrlSchema,
-  aspect: z.enum(VIDEO_ASPECT_VALUES),
-  maxDuration: z.number().max(LIMITS.maxVideoDurationSeconds).optional(),
-  alt: z.string().optional(),
-});
-
 const dividerElementSchema = z.object({
   type: z.literal(ELEMENT_TYPE.divider),
 });
@@ -434,7 +418,6 @@ const groupElementSchema = z.object({
 const elementSchema = z.discriminatedUnion("type", [
   textElementSchema,
   imageElementSchema,
-  videoElementSchema,
   dividerElementSchema,
   spacerElementSchema,
   progressElementSchema,
@@ -490,7 +473,7 @@ export const rootSchema = z
         if (mediaCount > 1) {
           ctx.addIssue({
             code: "custom",
-            message: `cannot have more than 1 media element (image, video, or grid)`,
+            message: `cannot have more than 1 media element (image or grid)`,
             path: ["elements", "children"],
           });
         }
@@ -524,7 +507,7 @@ export const firstPageRootSchema = rootSchema.superRefine((root, ctx) => {
     ctx.addIssue({
       code: "custom",
       message:
-        "first page must have at least one interactive element (button_group, slider, text_input, toggle) or media element (image, video, grid)",
+        "first page must have at least one interactive element (button_group, slider, text_input, toggle) or media element (image, grid)",
       path: ["page", "elements", "children"],
     });
   }

package/src/server/parseRequest.ts

@@ -1,6 +1,6 @@
 import { payloadSchema, type SnapAction } from "../schemas";
 import { decodePayload, verifyJFSRequestBody } from "./verify";
-import { z } from "zod/v4";
+import { z } from "zod";
 
 /** Default replay window per SPEC.md § Replay Protection (5 minutes). */
 const DEFAULT_SNAP_POST_MAX_SKEW_SECONDS = 300 as const;

package/src/ui/README.md

@@ -0,0 +1,50 @@
+# Theme colors in `@farcaster/snap/ui`
+
+This document explains how colors flow through snap pages — from the snap JSON spec to what clients render.
+
+## Named palette
+
+Snaps use a fixed set of named colors called the **palette**:
+
+| Name     | Light hex | Dark hex  |
+| -------- | --------- | --------- |
+| `gray`   | `#8F8F8F` | `#8F8F8F` |
+| `blue`   | `#006BFF` | `#006FFE` |
+| `red`    | `#FC0036` | `#F13342` |
+| `amber`  | `#FFAE00` | `#FFAE00` |
+| `green`  | `#28A948` | `#00AC3A` |
+| `teal`   | `#00AC96` | `#00AA96` |
+| `purple` | `#8B5CF6` | `#A78BFA` |
+| `pink`   | `#F32782` | `#F12B82` |
+
+These are exported from `@farcaster/snap` as `PALETTE_LIGHT_HEX`, `PALETTE_DARK_HEX`, and the `PaletteColor` type. Clients resolve the correct hex for their current light/dark mode.
+
+## Page-level accent (`page.theme.accent`)
+
+A snap page may declare a single accent color for the whole page:
+
+```json
+{
+  "page": {
+    "theme": { "accent": "blue" }
+  }
+}
+```
+
+`accent` must be a `PaletteColor` name. When `theme` is omitted, schema validation defaults it to `"purple"` (`DEFAULT_THEME_ACCENT`).
+
+The accent is the color used for all components on the page that don't have an explicit color set.
+
+## Per-element explicit colors
+
+Some elements accept a `color` prop:
+
+- `progress` — color name or `"accent"`
+- `bar_chart` — color name or `"accent"` at chart level; color name only per-bar
+- `grid` cells — `#rrggbb` hex
+
+When `color` is `"accent"` (or omitted), the element uses the accent color. When it is a specific color name or hex value, that color is **explicit** and independent of `page.theme.accent`.
+
+## Light/dark mode
+
+Mode is determined by the **client**, not by snap JSON. Snap JSON carries no light/dark setting. Clients select `PALETTE_LIGHT_HEX` or `PALETTE_DARK_HEX` based on their current mode.

package/src/ui/bar-chart.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import {
+  BAR_CHART_COLOR_VALUES,
+  LIMITS,
+  PALETTE_COLOR_VALUES,
+} from "../constants.js";
+
+export const barChartProps = z.object({
+  bars: z
+    .array(
+      z.object({
+        label: z.string(),
+        value: z.number().nonnegative(),
+        color: z.enum(PALETTE_COLOR_VALUES).optional(),
+      }),
+    )
+    .min(1)
+    .max(LIMITS.maxBarChartBars),
+  max: z.number().nonnegative().optional(),
+  color: z.enum(BAR_CHART_COLOR_VALUES).optional(),
+});
+
+export type BarChartProps = z.infer<typeof barChartProps>;

package/src/ui/button-group.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { BUTTON_GROUP_STYLE_VALUES, LIMITS } from "../constants.js";
+
+export const buttonGroupProps = z.object({
+  name: z.string().min(1),
+  options: z
+    .array(z.string())
+    .min(LIMITS.minButtonGroupOptions)
+    .max(LIMITS.maxButtonGroupOptions),
+  style: z.enum(BUTTON_GROUP_STYLE_VALUES).optional(),
+});
+
+export type ButtonGroupProps = z.infer<typeof buttonGroupProps>;

package/src/ui/button.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { BUTTON_ACTION_VALUES, BUTTON_STYLE_VALUES } from "../constants.js";
+
+export const actionButtonProps = z.object({
+  label: z.string(),
+  action: z.enum(BUTTON_ACTION_VALUES),
+  target: z.string(),
+  style: z.enum(BUTTON_STYLE_VALUES).optional(),
+});
+
+export type ActionButtonProps = z.infer<typeof actionButtonProps>;
+
+/** Same schema as `actionButtonProps` (legacy export name). */
+export const buttonProps = actionButtonProps;
+export type ButtonProps = ActionButtonProps;

package/src/ui/catalog.ts

@@ -0,0 +1,128 @@
+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 { 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 { 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({
+  buttonIndex: 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(),
+});
+
+/**
+ * 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.
+ */
+export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
+  components: {
+    Text: {
+      props: textProps,
+      description:
+        "Snap text block — style: title | body | caption | label; optional align.",
+    },
+    Image: {
+      props: imageProps,
+      description: "HTTPS image with fixed aspect ratio.",
+    },
+    Divider: {
+      props: dividerProps,
+      description: "Horizontal rule between blocks.",
+    },
+    Spacer: {
+      props: spacerProps,
+      description: "Vertical whitespace — size small | medium | large.",
+    },
+    Progress: {
+      props: progressProps,
+      description:
+        "Horizontal progress bar (value/max, optional label and color).",
+    },
+    List: {
+      props: listProps,
+      description:
+        "Ordered / unordered / plain list; max 4 items per snap spec.",
+    },
+    Grid: {
+      props: gridProps,
+      description:
+        "Rows×cols cell grid; optional interactive empty cells for games.",
+    },
+    TextInput: {
+      props: textInputProps,
+      description: "Single-line input; `name` becomes POST inputs key.",
+    },
+    Slider: {
+      props: sliderProps,
+      description: "Numeric slider; `name` becomes POST inputs key.",
+    },
+    ButtonGroup: {
+      props: buttonGroupProps,
+      description:
+        "Exclusive choice; `name` and selected option go into POST inputs.",
+    },
+    Toggle: {
+      props: toggleProps,
+      description: "Boolean toggle; `name` becomes POST inputs key.",
+    },
+    BarChart: {
+      props: barChartProps,
+      description:
+        "Vertical bar chart for labeled values — poll results, rankings, breakdowns.",
+    },
+    Group: {
+      props: groupProps,
+      description:
+        "Button row (`layout: row`) or 2-column grid (`layout: grid`); use `children` element ids only (no nested JSON objects).",
+    },
+    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.",
+    },
+    ActionButton: {
+      props: actionButtonProps,
+      description:
+        "Snap action button: post (next page), link (browser), mini_app, sdk — target is HTTPS URL or SDK id.",
+    },
+  },
+  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_sdk: {
+      description:
+        "Run a Farcaster client SDK action (cast:view, user:follow, …).",
+      params: snapTargetParams,
+    },
+  },
+});

package/src/ui/divider.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+
+export const dividerProps = z.object({});
+
+export type DividerProps = z.infer<typeof dividerProps>;

package/src/ui/grid.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import {
+  GRID_CELL_SIZE_VALUES,
+  GRID_GAP_VALUES,
+  HEX_COLOR_6_RE,
+  LIMITS,
+} from "../constants.js";
+
+const gridCellZ = z.object({
+  row: z.number().int().nonnegative(),
+  col: z.number().int().nonnegative(),
+  color: z.string().regex(HEX_COLOR_6_RE).optional(),
+  content: z.string().optional(),
+});
+
+export const gridProps = z.object({
+  cols: z.number().int().min(LIMITS.minGridCols).max(LIMITS.maxGridCols),
+  rows: z.number().int().min(LIMITS.minGridRows).max(LIMITS.maxGridRows),
+  cells: z.array(gridCellZ),
+  cellSize: z.enum(GRID_CELL_SIZE_VALUES).optional(),
+  gap: z.enum(GRID_GAP_VALUES).optional(),
+  interactive: z.boolean().optional(),
+});
+
+export type GridProps = z.infer<typeof gridProps>;

package/src/ui/group.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+
+export const groupProps = z.object({
+  layout: z.enum(["row", "grid"]),
+});
+
+export type GroupProps = z.infer<typeof groupProps>;

package/src/ui/image.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import { IMAGE_ASPECT_VALUES } from "../constants.js";
+
+export const imageProps = z.object({
+  url: z.string(),
+  aspect: z.enum(IMAGE_ASPECT_VALUES),
+  alt: z.string().optional(),
+});
+
+export type ImageProps = z.infer<typeof imageProps>;

package/src/ui/index.ts

@@ -0,0 +1,47 @@
+export { snapJsonRenderSchema } from "./schema.js";
+export { snapJsonRenderCatalog } from "./catalog.js";
+
+export { textProps } from "./text.js";
+export type { TextProps } from "./text.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 { 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";

package/src/ui/list.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { LIMITS, LIST_STYLE_VALUES } from "../constants.js";
+
+const listItemZ = z.object({
+  content: z.string(),
+  trailing: z.string().optional(),
+});
+
+export const listProps = z.object({
+  style: z.enum(LIST_STYLE_VALUES).optional(),
+  items: z
+    .array(listItemZ)
+    .min(LIMITS.minListItems)
+    .max(LIMITS.maxListItems),
+});
+
+export type ListProps = z.infer<typeof listProps>;

package/src/ui/progress.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import { PROGRESS_COLOR_VALUES } from "../constants.js";
+
+export const progressProps = z.object({
+  value: z.number(),
+  max: z.number(),
+  label: z.string().optional(),
+  color: z.enum(PROGRESS_COLOR_VALUES).optional(),
+});
+
+export type ProgressProps = z.infer<typeof progressProps>;

package/src/ui/schema.ts

@@ -0,0 +1,37 @@
+import { defineSchema } from "@json-render/core";
+
+/**
+ * json-render spec shape: flat `root` + `elements` map (see [json-render](https://json-render.dev/)).
+ * Component `type` strings must match keys in {@link ./catalog.ts}.
+ */
+export const snapJsonRenderSchema = defineSchema(
+  (s) => ({
+    spec: s.object({
+      root: s.string(),
+      elements: s.record(
+        s.object({
+          type: s.ref("catalog.components"),
+          props: s.propsOf("catalog.components"),
+          children: { ...s.array(s.string()), optional: true },
+        }),
+      ),
+    }),
+    catalog: s.object({
+      components: s.map({
+        props: s.zod(),
+        description: s.string(),
+      }),
+      actions: s.map({
+        description: s.string(),
+        params: { ...s.zod(), optional: true },
+      }),
+    }),
+  }),
+  {
+    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 / sdk per SPEC.md.",
+    ],
+  },
+);

package/src/ui/slider.ts

@@ -0,0 +1,14 @@
+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 type SliderProps = z.infer<typeof sliderProps>;

package/src/ui/spacer.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+import { SPACER_SIZE_VALUES } from "../constants.js";
+
+export const spacerProps = z.object({
+  size: z.enum(SPACER_SIZE_VALUES).optional(),
+});
+
+export type SpacerProps = z.infer<typeof spacerProps>;

package/src/ui/stack.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+
+export const stackProps = z.object({});
+
+export type StackProps = z.infer<typeof stackProps>;

package/src/ui/text-input.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { LIMITS } from "../constants.js";
+
+export const textInputProps = z.object({
+  name: z.string().min(1),
+  placeholder: z.string().optional(),
+  maxLength: z
+    .number()
+    .int()
+    .positive()
+    .max(LIMITS.maxTextInputChars)
+    .optional(),
+});
+
+export type TextInputProps = z.infer<typeof textInputProps>;

package/src/ui/text.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import { TEXT_ALIGN_VALUES, TEXT_STYLE_VALUES } from "../constants.js";
+
+export const textProps = z.object({
+  style: z.enum(TEXT_STYLE_VALUES),
+  content: z.string(),
+  align: z.enum(TEXT_ALIGN_VALUES).optional(),
+});
+
+export type TextProps = z.infer<typeof textProps>;

package/src/ui/toggle.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export const toggleProps = z.object({
+  name: z.string().min(1),
+  label: z.string(),
+  value: z.boolean().optional(),
+});
+
+export type ToggleProps = z.infer<typeof toggleProps>;

package/src/validator.ts

@@ -1,4 +1,4 @@
-import { z } from "zod/v4";
+import { z } from "zod";
 import {
   BUTTON_GROUP_STYLE,
   DEFAULT_BUTTON_LAYOUT,
@@ -39,7 +39,6 @@ function estimateElementHeight(el: Element): number {
       return 48;
     }
     case ELEMENT_TYPE.image:
-    case ELEMENT_TYPE.video:
       return 180;
     case ELEMENT_TYPE.grid:
       return 180;