@farcaster/snap 2.0.0 → 2.0.2

package/src/react-native/v2/snap-view.tsx

@@ -0,0 +1,283 @@
+import type { ReactNode } from "react";
+import { useEffect, useMemo, useState } from "react";
+import { Platform, StyleSheet, Text, View } from "react-native";
+import { SnapThemeProvider, useSnapTheme, type SnapNativeColors } from "../theme";
+import { SnapViewCoreInner } from "../snap-view-core";
+import {
+  validateSnapResponse,
+  type ValidationResult,
+} from "@farcaster/snap";
+import type { SnapPage, SnapActionHandlers } from "../types";
+
+// ─── Constants ───────────────────────────────────────
+
+const SNAP_MAX_HEIGHT = 500;
+const SNAP_WARNING_HEIGHT = 700;
+
+// ─── Validation fallback ─────────────────────────────
+
+function SnapValidationFallback({ message }: { message?: string }) {
+  const { colors } = useSnapTheme();
+  return (
+    <View style={fallbackStyles.container}>
+      <Text style={[fallbackStyles.text, { color: colors.textSecondary }]}>
+        {message ? `Unable to render snap: ${message}` : "Unable to render snap"}
+      </Text>
+    </View>
+  );
+}
+
+const fallbackStyles = StyleSheet.create({
+  container: {
+    width: "100%",
+    padding: 16,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  text: {
+    fontSize: 14,
+  },
+});
+
+// ─── SnapViewV2 (with validation) ────────────────────
+
+export function SnapViewV2Inner({
+  snap,
+  handlers,
+  loading = false,
+  onValidationError,
+  validationErrorFallback,
+}: {
+  snap: SnapPage;
+  handlers: SnapActionHandlers;
+  loading?: boolean;
+  onValidationError?: (result: ValidationResult) => void;
+  validationErrorFallback?: ReactNode;
+}) {
+  const validation = useMemo(() => validateSnapResponse(snap), [snap]);
+  const valid = validation.valid;
+  const validationMessage = validation.issues[0]?.message;
+
+  useEffect(() => {
+    if (!valid) {
+      if (onValidationError) {
+        onValidationError(validation);
+      } else {
+        // eslint-disable-next-line no-console
+        console.warn("[Snap] validation issues:", validation.issues);
+      }
+    }
+  }, [valid, validation, onValidationError]);
+
+  if (!valid) {
+    if (validationErrorFallback === null) return null;
+    return (
+      <>{validationErrorFallback ?? <SnapValidationFallback message={validationMessage} />}</>
+    );
+  }
+
+  return (
+    <SnapViewCoreInner snap={snap} handlers={handlers} loading={loading} />
+  );
+}
+
+export function SnapViewV2({
+  snap,
+  handlers,
+  loading = false,
+  appearance = "dark",
+  colors,
+  onValidationError,
+  validationErrorFallback,
+}: {
+  snap: SnapPage;
+  handlers: SnapActionHandlers;
+  loading?: boolean;
+  appearance?: "light" | "dark";
+  colors?: Partial<SnapNativeColors>;
+  onValidationError?: (result: ValidationResult) => void;
+  validationErrorFallback?: ReactNode;
+}) {
+  return (
+    <SnapThemeProvider appearance={appearance} colors={colors}>
+      <SnapViewV2Inner
+        snap={snap}
+        handlers={handlers}
+        loading={loading}
+        onValidationError={onValidationError}
+        validationErrorFallback={validationErrorFallback}
+      />
+    </SnapThemeProvider>
+  );
+}
+
+// ─── SnapCardV2 (card frame + height limits) ─────────
+
+function SnapCardV2Inner({
+  snap,
+  handlers,
+  loading,
+  borderRadius,
+  showOverflowWarning,
+  onValidationError,
+  validationErrorFallback,
+  actionError,
+  appearance,
+  plain,
+}: {
+  snap: SnapPage;
+  handlers: SnapActionHandlers;
+  loading?: boolean;
+  borderRadius: number;
+  showOverflowWarning: boolean;
+  onValidationError?: (result: ValidationResult) => void;
+  validationErrorFallback?: ReactNode;
+  actionError?: string | null;
+  appearance: "light" | "dark";
+  plain: boolean;
+}) {
+  const { colors } = useSnapTheme();
+  const [contentHeight, setContentHeight] = useState(0);
+
+  const content = (
+    <SnapViewV2Inner
+      snap={snap}
+      handlers={handlers}
+      loading={loading}
+      onValidationError={onValidationError}
+      validationErrorFallback={validationErrorFallback}
+    />
+  );
+
+  if (plain) {
+    return content;
+  }
+
+  const overflowAmount = showOverflowWarning ? contentHeight - SNAP_MAX_HEIGHT : 0;
+
+  return (
+    <>
+      <View
+        style={{
+          borderRadius,
+          borderWidth: 1,
+          borderColor: colors.border,
+          backgroundColor: colors.surface,
+          maxHeight: showOverflowWarning ? undefined : SNAP_MAX_HEIGHT,
+          overflow: "hidden",
+          minHeight: 120,
+        }}
+      >
+        <View
+          collapsable={false}
+          onLayout={(e) => setContentHeight(Math.round(e.nativeEvent.layout.height))}
+          style={{ paddingHorizontal: 16, paddingVertical: 16 }}
+        >
+          {content}
+        </View>
+        {showOverflowWarning && contentHeight > SNAP_MAX_HEIGHT && (
+          <View style={{ position: "absolute", top: SNAP_MAX_HEIGHT, left: 0, right: 0, height: overflowAmount, zIndex: 10, pointerEvents: "none" }}>
+            <View style={{ height: 1, borderTopWidth: 1, borderStyle: "dashed", borderColor: "rgba(255,100,100,0.6)" }} />
+            <View style={{ position: "absolute", top: -10, right: 4, backgroundColor: "rgba(0,0,0,0.7)", paddingHorizontal: 4, paddingVertical: 1, borderRadius: 3 }}>
+              <Text style={{ fontSize: 10, color: "rgba(255,100,100,0.7)", fontFamily: Platform.select({ ios: "Menlo", default: "monospace" }) }}>{SNAP_MAX_HEIGHT}px</Text>
+            </View>
+            <View style={{ flex: 1, backgroundColor: "rgba(255,50,50,0.15)" }} />
+          </View>
+        )}
+      </View>
+      {actionError && (
+        <Text
+          style={{
+            paddingHorizontal: 12,
+            paddingVertical: 8,
+            fontSize: 13,
+            color:
+              appearance === "dark"
+                ? "rgba(255,100,100,0.9)"
+                : "rgba(200,0,0,0.8)",
+          }}
+        >
+          {actionError}
+        </Text>
+      )}
+    </>
+  );
+}
+
+export function SnapCardV2({
+  snap,
+  handlers,
+  loading = false,
+  appearance = "dark",
+  colors,
+  borderRadius = 16,
+  showOverflowWarning = false,
+  onValidationError,
+  validationErrorFallback,
+  actionError,
+  plain = false,
+}: {
+  snap: SnapPage;
+  handlers: SnapActionHandlers;
+  loading?: boolean;
+  appearance?: "light" | "dark";
+  colors?: Partial<SnapNativeColors>;
+  borderRadius?: number;
+  showOverflowWarning?: boolean;
+  onValidationError?: (result: ValidationResult) => void;
+  validationErrorFallback?: ReactNode;
+  actionError?: string | null;
+  plain?: boolean;
+}) {
+  return (
+    <SnapThemeProvider appearance={appearance} colors={colors}>
+      <SnapCardV2Inner
+        snap={snap}
+        handlers={handlers}
+        loading={loading}
+        borderRadius={borderRadius}
+        showOverflowWarning={showOverflowWarning}
+        onValidationError={onValidationError}
+        validationErrorFallback={validationErrorFallback}
+        actionError={actionError}
+        appearance={appearance}
+        plain={plain}
+      />
+    </SnapThemeProvider>
+  );
+}
+
+const cardStyles = StyleSheet.create({
+  frameRing: { alignSelf: "stretch" },
+  card: { borderWidth: 1, minHeight: 120, overflow: "hidden" },
+  body: { paddingHorizontal: 16, paddingVertical: 16 },
+  actionError: { paddingHorizontal: 12, paddingVertical: 8, fontSize: 13 },
+  warningOverlay: {
+    position: "absolute",
+    top: SNAP_MAX_HEIGHT,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    zIndex: 10,
+  },
+  warningLine: {
+    height: 1,
+    borderTopWidth: 1,
+    borderStyle: "dashed",
+    borderColor: "rgba(255,100,100,0.6)",
+  },
+  warningLabel: {
+    position: "absolute",
+    top: -10,
+    right: 4,
+    backgroundColor: "rgba(0,0,0,0.7)",
+    paddingHorizontal: 4,
+    paddingVertical: 1,
+    borderRadius: 3,
+  },
+  warningLabelText: {
+    fontSize: 10,
+    color: "rgba(255,100,100,0.7)",
+    fontFamily: Platform.select({ ios: "Menlo", default: "monospace" }),
+  },
+});

package/src/schemas.ts

@@ -2,13 +2,10 @@ import { z } from "zod";
 import type { Spec } from "@json-render/core";
 import {
   EFFECT_VALUES,
-  SPEC_VERSION,
+  SUPPORTED_SPEC_VERSIONS,
+  type SpecVersion,
 } from "./constants";
-import {
-  DEFAULT_THEME_ACCENT,
-  PALETTE_COLOR_VALUES,
-} from "./colors";
-import { type SnapDataStore } from "./dataStore";
+import { DEFAULT_THEME_ACCENT, PALETTE_COLOR_VALUES } from "./colors";
 
 // ─── Theme ─────────────────────────────────────────────
 
@@ -28,7 +25,7 @@ const themeSchema = z
 
 export const snapResponseSchema = z
   .object({
-    version: z.literal(SPEC_VERSION),
+    version: z.enum(SUPPORTED_SPEC_VERSIONS),
     theme: themeSchema.optional().default({ accent: DEFAULT_THEME_ACCENT }),
     effects: z.array(z.enum(EFFECT_VALUES)).optional(),
     ui: z.custom<Spec>(
@@ -43,7 +40,41 @@ export const snapResponseSchema = z
   .strict();
 
 export type SnapResponse = z.infer<typeof snapResponseSchema>;
-export type SnapHandlerResult = z.input<typeof snapResponseSchema>;
+
+/**
+ * Permissive element input type for snap handler authors.
+ * Allows dynamic element construction without requiring exact UIElement types.
+ */
+export type SnapElementInput = {
+  type: string;
+  props?: Record<string, unknown>;
+  children?: string[];
+  on?: Record<string, unknown>;
+  [key: string]: unknown;
+};
+
+/**
+ * Permissive input type for the `ui` field in snap handler return values.
+ * Accepts dynamically-built element maps (e.g. `Record<string, SnapElementInput>`)
+ * without requiring exact UIElement types.
+ */
+export type SnapSpecInput = {
+  root: string;
+  elements: Record<string, SnapElementInput>;
+  state?: Record<string, unknown>;
+};
+
+/**
+ * Return type for snap handler functions.
+ * Uses permissive input types so handlers can build elements dynamically
+ * without type casts. Runtime validation via the Zod schema still catches invalid shapes.
+ */
+export type SnapHandlerResult = {
+  version: SpecVersion;
+  theme?: { accent?: z.input<typeof themeAccentSchema> };
+  effects?: z.input<typeof snapResponseSchema>["effects"];
+  ui: SnapSpecInput;
+};
 
 // ─── POST payload ──────────────────────────────────────
 
@@ -54,14 +85,37 @@ const postInputValueSchema = z.union([
   z.array(z.string()),
 ]);
 
+const standaloneSurfaceSchema = z.object({
+  type: z.literal("standalone"),
+});
+
+const castSurfaceSchema = z.object({
+  type: z.literal("cast"),
+  cast: z.object({
+    hash: z.string(),
+    author: z.object({
+      fid: z.number().int().nonnegative(),
+    }),
+  }),
+});
+
+const surfaceSchema = z.discriminatedUnion("type", [
+  castSurfaceSchema,
+  standaloneSurfaceSchema,
+]);
+
 export const payloadSchema = z
   .object({
-    fid: z.number().int().nonnegative(),
+    fid: z.number().int().nonnegative().optional(), // deprecated in favor of user.fid
     inputs: z.record(z.string(), postInputValueSchema).default({}),
-    button_index: z.number().int().nonnegative(),
     timestamp: z.number().int(),
+    audience: z.string(),
+    user: z.object({
+      fid: z.number().int().nonnegative(),
+    }),
+    surface: surfaceSchema,
   })
-  .strict();
+  .strip();
 
 export type SnapPayload = z.infer<typeof payloadSchema>;
 
@@ -74,11 +128,9 @@ const snapGetActionSchema = z.object({
 
 export type SnapGetAction = z.infer<typeof snapGetActionSchema>;
 
-const snapPostActionSchema = payloadSchema
-  .extend({
-    type: z.literal(ACTION_TYPE_POST),
-  })
-  .strict();
+const snapPostActionSchema = payloadSchema.extend({
+  type: z.literal(ACTION_TYPE_POST),
+});
 
 export type SnapPostAction = z.infer<typeof snapPostActionSchema>;
 
@@ -92,7 +144,6 @@ export type SnapAction = z.infer<typeof snapActionSchema>;
 export type SnapContext = {
   action: SnapAction;
   request: Request;
-  data: SnapDataStore;
 };
 
 export type SnapFunction = (ctx: SnapContext) => Promise<SnapHandlerResult>;

package/src/server/parseRequest.ts

@@ -29,6 +29,14 @@ export type ParseRequestError =
   | {
       type: "signature";
       message: string;
+    }
+  | {
+      type: "origin_mismatch";
+      message: string;
+    }
+  | {
+      type: "fid_mismatch";
+      message: string;
     };
 
 export type ParseRequestOptions = {
@@ -43,6 +51,11 @@ export type ParseRequestOptions = {
    * potential replays. Defaults to 300 (5 minutes) when not provided.
    */
   maxSkewSeconds?: number;
+
+  /**
+   * The origin of the request. Derived from the request when not provided.
+   */
+  requestOrigin?: string;
 };
 
 export type ParseRequestResult =
@@ -107,6 +120,18 @@ export async function parseRequest(
     };
   }
 
+  const payloadParsed = payloadSchema.safeParse(
+    decodePayload(parsed.data.payload),
+  );
+  if (!payloadParsed.success) {
+    return {
+      success: false,
+      error: { type: "validation", issues: payloadParsed.error.issues },
+    };
+  }
+
+  const body = payloadParsed.data;
+
   if (!options.skipJFSVerification) {
     const jfs = await verifyJFSRequestBody(parsed.data);
     if (!jfs.valid) {
@@ -115,28 +140,62 @@ export async function parseRequest(
         error: { type: "signature", message: jfs.error.message },
       };
     }
+    if (jfs.signingUserFid !== body.user.fid) {
+      return {
+        success: false,
+        error: {
+          type: "fid_mismatch",
+          message: `JFS header fid "${jfs.signingUserFid}" does not match user.fid "${body.user.fid}"`,
+        },
+      };
+    }
   }
 
-  const payloadParsed = payloadSchema.safeParse(
-    decodePayload(parsed.data.payload),
-  );
-  if (!payloadParsed.success) {
+  if (Math.abs(nowSec - body.timestamp) > maxSkew) {
     return {
       success: false,
-      error: { type: "validation", issues: payloadParsed.error.issues },
+      error: {
+        type: "replay",
+        message: `timestamp outside allowed skew of ${maxSkew}s`,
+      },
     };
   }
 
-  const body = payloadParsed.data;
-  if (Math.abs(nowSec - body.timestamp) > maxSkew) {
+  // Audience validation: ensure the payload audience matches the server origin.
+  let expectedOrigin = options.requestOrigin;
+  if (expectedOrigin === undefined) {
+    try {
+      const url = new URL(request.url);
+      const proto =
+        request.headers.get("x-forwarded-proto") ??
+        url.protocol.replace(":", "");
+      const host = request.headers.get("x-forwarded-host") ?? url.host;
+      expectedOrigin = `${proto}://${host}`;
+    } catch {
+      // do nothing
+    }
+  }
+
+  if (expectedOrigin !== undefined && body.audience !== expectedOrigin) {
     return {
       success: false,
       error: {
-        type: "replay",
-        message: `timestamp outside allowed skew of ${maxSkew}s`,
+        type: "origin_mismatch",
+        message: `payload audience "${body.audience}" does not match expected origin "${expectedOrigin}"`,
+      },
+    };
+  }
+
+  if (body.fid !== undefined && body.fid !== body.user.fid) {
+    return {
+      success: false,
+      error: {
+        type: "fid_mismatch",
+        message: `fid "${body.fid}" does not match user.fid "${body.user.fid}"`,
       },
     };
   }
+
   return {
     success: true,
     action: {

package/src/server/verify.ts

@@ -27,6 +27,7 @@ export async function verifyJFSRequestBody<TPayload>(
     }
   | {
       valid: true;
+      signingUserFid: number; // the FID of the user who signed the request
       data: TPayload;
     }
 > {
@@ -108,6 +109,7 @@ export async function verifyJFSRequestBody<TPayload>(
   return {
     valid: true,
     data: payload,
+    signingUserFid: header.fid,
   };
 }
 

package/src/ui/README.md

@@ -8,14 +8,14 @@ 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` |
+| `gray`   | `#6E6A86` | `#908CAA` |
+| `blue`   | `#286983` | `#9CCFD8` |
+| `red`    | `#B4637A` | `#EB6F92` |
+| `amber`  | `#EA9D34` | `#F6C177` |
+| `green`  | `#3E8F8F` | `#56D4A4` |
+| `teal`   | `#56949F` | `#3E8FB0` |
+| `purple` | `#907AA9` | `#C4A7E7` |
+| `pink`   | `#D7827E` | `#EBBCBA` |
 
 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.
 

package/src/ui/badge.ts

@@ -2,10 +2,12 @@ import { z } from "zod";
 import { PROGRESS_COLOR_VALUES } from "../colors.js";
 import { ICON_NAMES } from "./icon.js";
 
+export const BADGE_VARIANTS = ["default", "outline"] as const;
 export const BADGE_MAX_LABEL_CHARS = 30;
 
 export const badgeProps = z.object({
   label: z.string().min(1).max(BADGE_MAX_LABEL_CHARS),
+  variant: z.enum(BADGE_VARIANTS).optional(),
   color: z.enum(PROGRESS_COLOR_VALUES).optional(),
   icon: z.enum(ICON_NAMES).optional(),
 });

package/src/ui/bar-chart.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { BAR_CHART_COLOR_VALUES, PALETTE_COLOR_VALUES } from "../colors.js";
+import {
+  BAR_CHART_MAX_BARS,
+  BAR_CHART_LABEL_MAX_CHARS,
+} from "../constants.js";
+
+export const barChartProps = z
+  .object({
+    bars: z
+      .array(
+        z.object({
+          label: z.string().min(1).max(BAR_CHART_LABEL_MAX_CHARS),
+          value: z.number().nonnegative(),
+          color: z.enum(PALETTE_COLOR_VALUES).optional(),
+        }),
+      )
+      .min(1)
+      .max(BAR_CHART_MAX_BARS),
+    max: z.number().nonnegative().optional(),
+    color: z.enum(BAR_CHART_COLOR_VALUES).optional(),
+  })
+  .superRefine((val, ctx) => {
+    if (val.max !== undefined) {
+      for (let i = 0; i < val.bars.length; i++) {
+        const bar = val.bars[i]!;
+        if (bar.value > val.max) {
+          ctx.addIssue({
+            code: "custom",
+            message: `bar value (${bar.value}) exceeds chart max (${val.max})`,
+            path: ["bars", i, "value"],
+          });
+        }
+      }
+    }
+  });
+
+export type BarChartProps = z.infer<typeof barChartProps>;

package/src/ui/button.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { ICON_NAMES } from "./icon.js";
 
-export const BUTTON_VARIANTS = ["default", "secondary", "outline", "ghost"] as const;
+export const BUTTON_VARIANTS = ["secondary", "primary"] as const;
 export const BUTTON_MAX_LABEL_CHARS = 30;
 
 export const buttonProps = z.object({

package/src/ui/catalog.ts

@@ -15,6 +15,8 @@ import { separatorProps } from "./separator.js";
 import { sliderProps } from "./slider.js";
 import { stackProps } from "./stack.js";
 import { textProps } from "./text.js";
+import { barChartProps } from "./bar-chart.js";
+import { cellGridProps } from "./cell-grid.js";
 
 const snapClientParams = z.object({
   client_action: z.record(z.string(), z.unknown()),
@@ -31,7 +33,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
     badge: {
       props: badgeProps,
       description:
-        "Inline label — variant: default | secondary | destructive | outline.",
+        "Inline label — variant: default (filled) or outline (bordered). Optional color and icon.",
     },
     button: {
       props: buttonProps,
@@ -95,7 +97,17 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
     text: {
       props: textProps,
       description:
-        "Text block — size: lg (heading), md (body, default), sm (caption). Optional weight and align.",
+        "Text block — size: md (body, default), sm (caption). Optional weight and align.",
+    },
+    bar_chart: {
+      props: barChartProps,
+      description:
+        "Horizontal bar chart — 1–6 bars with label, value, and optional per-bar color. Optional max and default color.",
+    },
+    cell_grid: {
+      props: cellGridProps,
+      description:
+        "Cell grid — sparse colored cells on a rows×cols grid. Optional gap and selection mode (taps write to inputs[name]).",
     },
   },
   actions: {
@@ -105,7 +117,11 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
       params: z.object({ target: z.string() }),
     },
     open_url: {
-      description: "Open target URL in the system browser.",
+      description: "Open external URL in browser.",
+      params: z.object({ target: z.string() }),
+    },
+    open_snap: {
+      description: "Open a snap URL inline. The client renders the target as a snap rather than opening a browser.",
       params: z.object({ target: z.string() }),
     },
     open_mini_app: {