@farcaster/snap 1.3.1 → 1.3.2

package/dist/ui/list.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+export declare const listProps: z.ZodObject<{
+    style: z.ZodOptional<z.ZodEnum<{
+        ordered: "ordered";
+        unordered: "unordered";
+        plain: "plain";
+    }>>;
+    items: z.ZodArray<z.ZodObject<{
+        content: z.ZodString;
+        trailing: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ListProps = z.infer<typeof listProps>;

package/dist/ui/list.js

@@ -0,0 +1,13 @@
+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),
+});

package/dist/ui/progress.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+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

@@ -0,0 +1,8 @@
+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(),
+});

package/dist/ui/schema.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 declare const snapJsonRenderSchema: import("@json-render/core").Schema<{
+    spec: import("@json-render/core").SchemaType<"object", {
+        root: import("@json-render/core").SchemaType<"string", unknown>;
+        elements: import("@json-render/core").SchemaType<"record", import("@json-render/core").SchemaType<"object", {
+            type: import("@json-render/core").SchemaType<"ref", string>;
+            props: import("@json-render/core").SchemaType<"propsOf", string>;
+            children: {
+                optional: true;
+                kind: "array";
+                inner?: import("@json-render/core").SchemaType<"string", unknown> | undefined;
+            };
+        }>>;
+    }>;
+    catalog: import("@json-render/core").SchemaType<"object", {
+        components: import("@json-render/core").SchemaType<"map", {
+            props: import("@json-render/core").SchemaType<"zod", unknown>;
+            description: import("@json-render/core").SchemaType<"string", unknown>;
+        }>;
+        actions: import("@json-render/core").SchemaType<"map", {
+            description: import("@json-render/core").SchemaType<"string", unknown>;
+            params: {
+                optional: true;
+                kind: "zod";
+                inner?: unknown;
+            };
+        }>;
+    }>;
+}>;

package/dist/ui/schema.js

@@ -0,0 +1,31 @@
+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/dist/ui/slider.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+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>;
+    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>;

package/dist/ui/slider.js

@@ -0,0 +1,11 @@
+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(),
+});

package/dist/ui/spacer.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+export declare const spacerProps: z.ZodObject<{
+    size: z.ZodOptional<z.ZodEnum<{
+        small: "small";
+        medium: "medium";
+        large: "large";
+    }>>;
+}, z.core.$strip>;
+export type SpacerProps = z.infer<typeof spacerProps>;

package/dist/ui/spacer.js

@@ -0,0 +1,5 @@
+import { z } from "zod";
+import { SPACER_SIZE_VALUES } from "../constants.js";
+export const spacerProps = z.object({
+    size: z.enum(SPACER_SIZE_VALUES).optional(),
+});

package/dist/ui/stack.d.ts

@@ -0,0 +1,3 @@
+import { z } from "zod";
+export declare const stackProps: z.ZodObject<{}, z.core.$strip>;
+export type StackProps = z.infer<typeof stackProps>;

package/dist/ui/stack.js

@@ -0,0 +1,2 @@
+import { z } from "zod";
+export const stackProps = z.object({});

package/dist/ui/text-input.d.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+export declare const textInputProps: z.ZodObject<{
+    name: z.ZodString;
+    placeholder: z.ZodOptional<z.ZodString>;
+    maxLength: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type TextInputProps = z.infer<typeof textInputProps>;

package/dist/ui/text-input.js

@@ -0,0 +1,12 @@
+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(),
+});

package/dist/ui/text.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+export declare const textProps: z.ZodObject<{
+    style: z.ZodEnum<{
+        title: "title";
+        body: "body";
+        caption: "caption";
+        label: "label";
+    }>;
+    content: z.ZodString;
+    align: z.ZodOptional<z.ZodEnum<{
+        left: "left";
+        center: "center";
+        right: "right";
+    }>>;
+}, z.core.$strip>;
+export type TextProps = z.infer<typeof textProps>;

package/dist/ui/text.js

@@ -0,0 +1,7 @@
+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(),
+});

package/dist/ui/toggle.d.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+export declare const toggleProps: z.ZodObject<{
+    name: z.ZodString;
+    label: z.ZodString;
+    value: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type ToggleProps = z.infer<typeof toggleProps>;

package/dist/ui/toggle.js

@@ -0,0 +1,6 @@
+import { z } from "zod";
+export const toggleProps = z.object({
+    name: z.string().min(1),
+    label: z.string(),
+    value: z.boolean().optional(),
+});

package/dist/validator.d.ts

@@ -1,4 +1,4 @@
-import { z } from "zod/v4";
+import { z } from "zod";
 export type ValidationResult = {
     valid: boolean;
     issues: z.core.$ZodIssue[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farcaster/snap",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Farcaster Snaps 🫰",
   "repository": {
     "type": "git",
@@ -20,6 +20,86 @@
       "types": "./dist/server/index.d.ts",
       "import": "./dist/server/index.js",
       "default": "./dist/server/index.js"
+    },
+    "./ui": {
+      "types": "./dist/ui/index.d.ts",
+      "import": "./dist/ui/index.js",
+      "default": "./dist/ui/index.js"
+    },
+    "./ui/text": {
+      "types": "./dist/ui/text.d.ts",
+      "import": "./dist/ui/text.js",
+      "default": "./dist/ui/text.js"
+    },
+    "./ui/image": {
+      "types": "./dist/ui/image.d.ts",
+      "import": "./dist/ui/image.js",
+      "default": "./dist/ui/image.js"
+    },
+    "./ui/divider": {
+      "types": "./dist/ui/divider.d.ts",
+      "import": "./dist/ui/divider.js",
+      "default": "./dist/ui/divider.js"
+    },
+    "./ui/spacer": {
+      "types": "./dist/ui/spacer.d.ts",
+      "import": "./dist/ui/spacer.js",
+      "default": "./dist/ui/spacer.js"
+    },
+    "./ui/progress": {
+      "types": "./dist/ui/progress.d.ts",
+      "import": "./dist/ui/progress.js",
+      "default": "./dist/ui/progress.js"
+    },
+    "./ui/list": {
+      "types": "./dist/ui/list.d.ts",
+      "import": "./dist/ui/list.js",
+      "default": "./dist/ui/list.js"
+    },
+    "./ui/grid": {
+      "types": "./dist/ui/grid.d.ts",
+      "import": "./dist/ui/grid.js",
+      "default": "./dist/ui/grid.js"
+    },
+    "./ui/text-input": {
+      "types": "./dist/ui/text-input.d.ts",
+      "import": "./dist/ui/text-input.js",
+      "default": "./dist/ui/text-input.js"
+    },
+    "./ui/slider": {
+      "types": "./dist/ui/slider.d.ts",
+      "import": "./dist/ui/slider.js",
+      "default": "./dist/ui/slider.js"
+    },
+    "./ui/button-group": {
+      "types": "./dist/ui/button-group.d.ts",
+      "import": "./dist/ui/button-group.js",
+      "default": "./dist/ui/button-group.js"
+    },
+    "./ui/toggle": {
+      "types": "./dist/ui/toggle.d.ts",
+      "import": "./dist/ui/toggle.js",
+      "default": "./dist/ui/toggle.js"
+    },
+    "./ui/bar-chart": {
+      "types": "./dist/ui/bar-chart.d.ts",
+      "import": "./dist/ui/bar-chart.js",
+      "default": "./dist/ui/bar-chart.js"
+    },
+    "./ui/group": {
+      "types": "./dist/ui/group.d.ts",
+      "import": "./dist/ui/group.js",
+      "default": "./dist/ui/group.js"
+    },
+    "./ui/stack": {
+      "types": "./dist/ui/stack.d.ts",
+      "import": "./dist/ui/stack.js",
+      "default": "./dist/ui/stack.js"
+    },
+    "./ui/button": {
+      "types": "./dist/ui/button.d.ts",
+      "import": "./dist/ui/button.js",
+      "default": "./dist/ui/button.js"
     }
   },
   "files": [
@@ -32,10 +112,11 @@
   "license": "MIT",
   "dependencies": {
     "@farcaster/jfs": "^0.3.0",
+    "@json-render/core": "^0.15.0",
     "viem": "^2.21.0"
   },
   "peerDependencies": {
-    "zod": "^3.25.0 || ^4.0.0"
+    "zod": "^4.0.0"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",

package/src/schemas.ts

@@ -1,4 +1,4 @@
-import { z } from "zod/v4";
+import { z } from "zod";
 import {
   BAR_CHART_COLOR_VALUES,
   BUTTON_ACTION,

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>;