@farcaster/snap 1.3.1 → 1.3.3

package/dist/ui/index.d.ts

@@ -0,0 +1,32 @@
+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/dist/ui/index.js

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

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.3",
   "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/index.ts

@@ -19,6 +19,7 @@ export {
   type SnapAction,
   type SnapContext,
   type SnapResponse,
+  type SnapResponseInput,
   type SnapFunction,
   type SnapPayload,
 } from "./schemas";

package/src/schemas.ts

@@ -1,4 +1,4 @@
-import { z } from "zod/v4";
+import { z } from "zod";
 import {
   BAR_CHART_COLOR_VALUES,
   BUTTON_ACTION,
@@ -536,6 +536,7 @@ export const payloadSchema = z
   .strict();
 
 export type SnapResponse = z.infer<typeof rootSchema>;
+export type SnapResponseInput = z.input<typeof rootSchema>;
 export type SnapPage = SnapResponse["page"];
 export type SnapPayload = z.infer<typeof payloadSchema>;
 
@@ -560,4 +561,4 @@ export type SnapContext = {
   request: Request;
 };
 
-export type SnapFunction = (ctx: SnapContext) => Promise<SnapResponse>;
+export type SnapFunction = (ctx: SnapContext) => Promise<SnapResponseInput>;

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;