@farcaster/snap 2.1.2 → 2.2.0

package/dist/colors.d.ts

@@ -24,6 +24,16 @@ export declare const PALETTE_COLOR_ACCENT: "accent";
 export declare const DEFAULT_THEME_ACCENT: "purple";
 export declare const PALETTE_COLOR_VALUES: readonly ["gray", "blue", "red", "amber", "green", "teal", "purple", "pink"];
 export type PaletteColor = (typeof PALETTE_COLOR_VALUES)[number];
+export declare function isSnapHexColorString(s: string): boolean;
+/**
+ * Resolve a snap color token for inline styles: `accent`, palette names, or
+ * literal `#rrggbb`. Unknown values fall back to `accentHex` (same as legacy
+ * `colorHex` behavior for non-hex strings).
+ */
+export declare function resolveSnapColorHex(color: string | undefined, opts: {
+    accentHex: string;
+    appearance: "light" | "dark";
+}): string;
 /** Light-mode hex for each palette color (emulator / reference client). */
 export declare const PALETTE_LIGHT_HEX: Record<PaletteColor, string>;
 /** Dark-mode hex for each palette color (reference). */

package/dist/colors.js

@@ -32,6 +32,28 @@ export const PALETTE_COLOR_VALUES = [
     PALETTE_COLOR.purple,
     PALETTE_COLOR.pink,
 ];
+/** Strict `#rrggbb` literal used by cell_grid (and clients that accept hex). */
+const SNAP_HEX_6 = /^#[0-9a-fA-F]{6}$/;
+export function isSnapHexColorString(s) {
+    return SNAP_HEX_6.test(s.trim());
+}
+/**
+ * Resolve a snap color token for inline styles: `accent`, palette names, or
+ * literal `#rrggbb`. Unknown values fall back to `accentHex` (same as legacy
+ * `colorHex` behavior for non-hex strings).
+ */
+export function resolveSnapColorHex(color, opts) {
+    if (!color || color === PALETTE_COLOR_ACCENT)
+        return opts.accentHex;
+    const trimmed = color.trim();
+    if (isSnapHexColorString(trimmed))
+        return trimmed;
+    const map = opts.appearance === "dark" ? PALETTE_DARK_HEX : PALETTE_LIGHT_HEX;
+    if (Object.hasOwn(map, trimmed)) {
+        return map[trimmed];
+    }
+    return opts.accentHex;
+}
 /** Light-mode hex for each palette color (emulator / reference client). */
 export const PALETTE_LIGHT_HEX = {
     gray: "#6E6A86",

package/dist/constants.d.ts

@@ -3,6 +3,7 @@ export declare const SPEC_VERSION_2: "2.0";
 export declare const SPEC_VERSION: "2.0";
 export declare const SUPPORTED_SPEC_VERSIONS: readonly ["1.0", "2.0"];
 export type SpecVersion = (typeof SUPPORTED_SPEC_VERSIONS)[number];
+export declare const SNAP_PAYLOAD_HEADER: "X-Snap-Payload";
 export declare const MEDIA_TYPE: "application/vnd.farcaster.snap+json";
 export declare const EFFECT_VALUES: readonly ["confetti"];
 export declare const POST_GRID_TAP_KEY: "grid_tap";

package/dist/constants.js

@@ -1,7 +1,11 @@
 export const SPEC_VERSION_1 = "1.0";
 export const SPEC_VERSION_2 = "2.0";
 export const SPEC_VERSION = SPEC_VERSION_2;
-export const SUPPORTED_SPEC_VERSIONS = [SPEC_VERSION_1, SPEC_VERSION_2];
+export const SUPPORTED_SPEC_VERSIONS = [
+    SPEC_VERSION_1,
+    SPEC_VERSION_2,
+];
+export const SNAP_PAYLOAD_HEADER = "X-Snap-Payload";
 export const MEDIA_TYPE = "application/vnd.farcaster.snap+json";
 export const EFFECT_VALUES = ["confetti"];
 // ─── Pixel grid ────────────────────────────────────────

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export type { Spec as SnapSpec, UIElement as SnapUIElement, } from "@json-render/core";
-export { SPEC_VERSION, SPEC_VERSION_1, SPEC_VERSION_2, SUPPORTED_SPEC_VERSIONS, type SpecVersion, MEDIA_TYPE, EFFECT_VALUES, POST_GRID_TAP_KEY, MAX_ELEMENTS, MAX_ROOT_CHILDREN, MAX_CHILDREN, MAX_DEPTH, } from "./constants.js";
-export { DEFAULT_THEME_ACCENT, PALETTE_COLOR, PALETTE_COLOR_ACCENT, PALETTE_COLOR_VALUES, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, type PaletteColor, } from "./colors.js";
-export { ACTION_TYPE_GET, ACTION_TYPE_POST, snapResponseSchema, payloadSchema, type SnapAction, type SnapContext, type SnapResponse, type SnapHandlerResult, type SnapElementInput, type SnapSpecInput, type SnapFunction, type SnapPayload, } from "./schemas.js";
+export { SPEC_VERSION, SPEC_VERSION_1, SPEC_VERSION_2, SUPPORTED_SPEC_VERSIONS, type SpecVersion, SNAP_PAYLOAD_HEADER, MEDIA_TYPE, EFFECT_VALUES, POST_GRID_TAP_KEY, MAX_ELEMENTS, MAX_ROOT_CHILDREN, MAX_CHILDREN, MAX_DEPTH, } from "./constants.js";
+export { DEFAULT_THEME_ACCENT, PALETTE_COLOR, PALETTE_COLOR_ACCENT, PALETTE_COLOR_VALUES, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, isSnapHexColorString, resolveSnapColorHex, type PaletteColor, } from "./colors.js";
+export { ACTION_TYPE_GET, ACTION_TYPE_POST, snapResponseSchema, payloadSchema, getPayloadSchema, type SnapAction, type SnapGetAction, type SnapContext, type SnapResponse, type SnapHandlerResult, type SnapElementInput, type SnapSpecInput, type SnapFunction, type SnapPayload, type SnapGetPayload, } from "./schemas.js";
 export { validateSnapResponse, type ValidationResult } from "./validator.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { SPEC_VERSION, SPEC_VERSION_1, SPEC_VERSION_2, SUPPORTED_SPEC_VERSIONS, MEDIA_TYPE, EFFECT_VALUES, POST_GRID_TAP_KEY, MAX_ELEMENTS, MAX_ROOT_CHILDREN, MAX_CHILDREN, MAX_DEPTH, } from "./constants.js";
-export { DEFAULT_THEME_ACCENT, PALETTE_COLOR, PALETTE_COLOR_ACCENT, PALETTE_COLOR_VALUES, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, } from "./colors.js";
-export { ACTION_TYPE_GET, ACTION_TYPE_POST, snapResponseSchema, payloadSchema, } from "./schemas.js";
+export { SPEC_VERSION, SPEC_VERSION_1, SPEC_VERSION_2, SUPPORTED_SPEC_VERSIONS, SNAP_PAYLOAD_HEADER, MEDIA_TYPE, EFFECT_VALUES, POST_GRID_TAP_KEY, MAX_ELEMENTS, MAX_ROOT_CHILDREN, MAX_CHILDREN, MAX_DEPTH, } from "./constants.js";
+export { DEFAULT_THEME_ACCENT, PALETTE_COLOR, PALETTE_COLOR_ACCENT, PALETTE_COLOR_VALUES, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, isSnapHexColorString, resolveSnapColorHex, } from "./colors.js";
+export { ACTION_TYPE_GET, ACTION_TYPE_POST, snapResponseSchema, payloadSchema, getPayloadSchema, } from "./schemas.js";
 export { validateSnapResponse } from "./validator.js";

package/dist/react/hooks/use-snap-colors.js

@@ -3,7 +3,7 @@ import { useMemo } from "react";
 import { useStateStore } from "@json-render/react";
 import { resolveSnapPaletteHex } from "../lib/resolve-palette-hex.js";
 import { useSnapPreviewPageAccent, useSnapAppearance } from "../accent-context.js";
-import { PALETTE_DARK_HEX, PALETTE_LIGHT_HEX } from "@farcaster/snap";
+import { resolveSnapColorHex } from "@farcaster/snap";
 /** Readable foreground color (black or white) for a given hex background. */
 export function pickForegroundForBg(hex) {
     const h = hex.replace(/^#/, "");
@@ -37,19 +37,12 @@ function buildSnapColors(accentName, mode) {
     const accent = resolveSnapPaletteHex(accentName, mode);
     const accentFg = pickForegroundForBg(accent);
     const neutrals = mode === "dark" ? NEUTRAL_DARK : NEUTRAL_LIGHT;
-    const paletteMap = mode === "dark" ? PALETTE_DARK_HEX : PALETTE_LIGHT_HEX;
     const accentHover = mode === "light"
         ? `color-mix(in srgb, ${accent} 82%, #000000)`
         : `color-mix(in srgb, ${accent} 78%, #ffffff)`;
     const outlineHover = `color-mix(in srgb, ${accent} 14%, ${neutrals.surface})`;
     const paletteHex = (name) => resolveSnapPaletteHex(name, mode);
-    const colorHex = (name) => {
-        if (!name || name === "accent")
-            return accent;
-        if (Object.hasOwn(paletteMap, name))
-            return paletteMap[name];
-        return accent;
-    };
+    const colorHex = (name) => resolveSnapColorHex(name, { accentHex: accent, appearance: mode });
     return {
         accent,
         accentFg,

package/dist/react-native/use-snap-palette.js

@@ -1,4 +1,4 @@
-import { DEFAULT_THEME_ACCENT, PALETTE_COLOR_VALUES, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, } from "@farcaster/snap";
+import { DEFAULT_THEME_ACCENT, PALETTE_COLOR_VALUES, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, resolveSnapColorHex, } from "@farcaster/snap";
 import { useStateStore } from "@json-render/react-native";
 import { useSnapTheme } from "./theme.js";
 function resolveHex(name, appearance) {
@@ -23,7 +23,7 @@ export function useSnapPalette() {
     const { get } = useStateStore();
     const accentName = themeAccentFromStore(get);
     const accentHex = resolveHex(accentName, mode);
-    const hex = (semantic) => semantic === "accent" ? accentHex : resolveHex(semantic, mode);
+    const hex = (semantic) => resolveSnapColorHex(semantic, { accentHex, appearance: mode });
     return { appearance: mode, accentName, accentHex, hex };
 }
 /** `#RRGGBB` + alpha → `rgba(...)` for React Native styles. */

package/dist/schemas.d.ts

@@ -89,10 +89,46 @@ export declare const payloadSchema: z.ZodObject<{
     }, z.core.$strip>], "type">;
 }, z.core.$strip>;
 export type SnapPayload = z.infer<typeof payloadSchema>;
+/** JFS payload shape for POST minus deprecated `fid`; used for GET auth via payload header. */
+export declare const getPayloadSchema: z.ZodObject<{
+    user: z.ZodObject<{
+        fid: z.ZodNumber;
+    }, z.core.$strip>;
+    timestamp: z.ZodNumber;
+    audience: z.ZodString;
+    surface: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"cast">;
+        cast: z.ZodObject<{
+            hash: z.ZodString;
+            author: z.ZodObject<{
+                fid: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"standalone">;
+    }, z.core.$strip>], "type">;
+}, z.core.$strip>;
+export type SnapGetPayload = z.infer<typeof getPayloadSchema>;
 export declare const ACTION_TYPE_GET: "get";
 export declare const ACTION_TYPE_POST: "post";
 declare const snapGetActionSchema: z.ZodObject<{
     type: z.ZodLiteral<"get">;
+    user: z.ZodOptional<z.ZodObject<{
+        fid: z.ZodNumber;
+    }, z.core.$strip>>;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+    audience: z.ZodOptional<z.ZodString>;
+    surface: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"cast">;
+        cast: z.ZodObject<{
+            hash: z.ZodString;
+            author: z.ZodObject<{
+                fid: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"standalone">;
+    }, z.core.$strip>], "type">>;
 }, z.core.$strip>;
 export type SnapGetAction = z.infer<typeof snapGetActionSchema>;
 declare const snapPostActionSchema: z.ZodObject<{
@@ -119,6 +155,22 @@ declare const snapPostActionSchema: z.ZodObject<{
 export type SnapPostAction = z.infer<typeof snapPostActionSchema>;
 export declare const snapActionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"get">;
+    user: z.ZodOptional<z.ZodObject<{
+        fid: z.ZodNumber;
+    }, z.core.$strip>>;
+    timestamp: z.ZodOptional<z.ZodNumber>;
+    audience: z.ZodOptional<z.ZodString>;
+    surface: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"cast">;
+        cast: z.ZodObject<{
+            hash: z.ZodString;
+            author: z.ZodObject<{
+                fid: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"standalone">;
+    }, z.core.$strip>], "type">>;
 }, z.core.$strip>, z.ZodObject<{
     fid: z.ZodOptional<z.ZodNumber>;
     inputs: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;

package/dist/schemas.js

@@ -47,22 +47,28 @@ const surfaceSchema = z.discriminatedUnion("type", [
     castSurfaceSchema,
     standaloneSurfaceSchema,
 ]);
+const fidSchema = z.number().int().nonnegative();
+const userSchema = z.object({ fid: fidSchema });
 export const payloadSchema = z
     .object({
-    fid: z.number().int().nonnegative().optional(), // deprecated in favor of user.fid
+    fid: fidSchema.optional(), // deprecated in favor of user.fid
     inputs: z.record(z.string(), postInputValueSchema).default({}),
     timestamp: z.number().int(),
     audience: z.string(),
-    user: z.object({
-        fid: z.number().int().nonnegative(),
-    }),
+    user: userSchema,
     surface: surfaceSchema,
 })
     .strip();
+/** JFS payload shape for POST minus deprecated `fid`; used for GET auth via payload header. */
+export const getPayloadSchema = payloadSchema.omit({ inputs: true, fid: true });
 export const ACTION_TYPE_GET = "get";
 export const ACTION_TYPE_POST = "post";
 const snapGetActionSchema = z.object({
     type: z.literal(ACTION_TYPE_GET),
+    user: userSchema.optional(),
+    timestamp: z.number().int().optional(),
+    audience: z.string().optional(),
+    surface: surfaceSchema.optional(),
 });
 const snapPostActionSchema = payloadSchema.extend({
     type: z.literal(ACTION_TYPE_POST),

package/dist/server/index.d.ts

@@ -1,3 +1,4 @@
-export { verifyJFSRequestBody, decodePayload, encodePayload } from "./verify.js";
+export { verifyJFS as verifyJFSRequestBody, // deprecated alias. drop in v3
+parseJfs, verifyJFS, decodePayload, encodePayload, } from "./verify.js";
 export { DEFAULT_SNAP_HUB_HTTP_BASE_URL, getActiveEd25519SignerKeysFromHubHttp, } from "./hubs.js";
 export { parseRequest, type ParseRequestError, type ParseRequestOptions, type ParseRequestResult, } from "./parseRequest.js";

package/dist/server/index.js

@@ -1,3 +1,4 @@
-export { verifyJFSRequestBody, decodePayload, encodePayload } from "./verify.js";
+export { verifyJFS as verifyJFSRequestBody, // deprecated alias. drop in v3
+parseJfs, verifyJFS, decodePayload, encodePayload, } from "./verify.js";
 export { DEFAULT_SNAP_HUB_HTTP_BASE_URL, getActiveEd25519SignerKeysFromHubHttp, } from "./hubs.js";
 export { parseRequest, } from "./parseRequest.js";

package/dist/server/parseRequest.d.ts

@@ -1,5 +1,5 @@
-import { type SnapAction } from "../schemas.js";
 import { z } from "zod";
+import { type SnapAction } from "../schemas.js";
 export type ParseRequestError = {
     type: "method_not_allowed";
     message: string;
@@ -47,7 +47,8 @@ export type ParseRequestResult = {
 };
 /**
  * Parse and validate Farcaster snap requests:
- * - `GET` is allowed for first-page loads and returns `{ type: "get" }`.
- * - `POST`: the body must be JSON in JFS form (`header` / `payload` / `signature`) even if JFS verification is skipped.
+ * - `GET`: returns `{ type: "get" }`, or optional viewer fields when `X-Snap-Payload`
+ *   carries a JFS compact string whose decoded payload validates against {@link getPayloadSchema}.
+ * - `POST`: the body must be a JFS envelope — either JSON `{ header, payload, signature }` or the same **compact** string form as GET (`BASE64URL(header).BASE64URL(payload).BASE64URL(signature)`), even if JFS verification is skipped.
  */
 export declare function parseRequest(request: Request, options?: ParseRequestOptions): Promise<ParseRequestResult>;

package/dist/server/parseRequest.js

@@ -1,85 +1,124 @@
-import { ACTION_TYPE_GET, ACTION_TYPE_POST, payloadSchema, } from "../schemas.js";
-import { decodePayload, verifyJFSRequestBody } from "./verify.js";
-import { z } from "zod";
+import { ACTION_TYPE_GET, ACTION_TYPE_POST, getPayloadSchema, payloadSchema, } from "../schemas.js";
+import { decodePayload, parseJfs, verifyJFS } from "./verify.js";
+import { SNAP_PAYLOAD_HEADER } from "../constants.js";
 const DEFAULT_SNAP_POST_MAX_SKEW_SECONDS = 300;
-const requestBodySchema = z.object({
-    header: z.string(),
-    payload: z.string(),
-    signature: z.string(),
-});
 /**
  * Parse and validate Farcaster snap requests:
- * - `GET` is allowed for first-page loads and returns `{ type: "get" }`.
- * - `POST`: the body must be JSON in JFS form (`header` / `payload` / `signature`) even if JFS verification is skipped.
+ * - `GET`: returns `{ type: "get" }`, or optional viewer fields when `X-Snap-Payload`
+ *   carries a JFS compact string whose decoded payload validates against {@link getPayloadSchema}.
+ * - `POST`: the body must be a JFS envelope — either JSON `{ header, payload, signature }` or the same **compact** string form as GET (`BASE64URL(header).BASE64URL(payload).BASE64URL(signature)`), even if JFS verification is skipped.
  */
 export async function parseRequest(request, options = {}) {
-    if (!["GET", "POST"].includes(request.method)) {
-        return {
-            success: false,
-            error: {
-                type: "method_not_allowed",
-                message: `expected POST, received ${request.method}`,
-            },
-        };
-    }
     if (request.method === "GET") {
-        return {
-            success: true,
-            action: { type: ACTION_TYPE_GET },
-        };
+        return await parseGetRequest(request, options);
     }
-    const maxSkew = options.maxSkewSeconds ?? DEFAULT_SNAP_POST_MAX_SKEW_SECONDS;
-    const nowSec = Math.floor(Date.now() / 1000);
-    const text = await request.text();
-    let jsonBody;
-    try {
-        jsonBody = JSON.parse(text);
+    if (request.method === "POST") {
+        return await parsePostRequest(request, options);
     }
-    catch {
+    return {
+        success: false,
+        error: {
+            type: "method_not_allowed",
+            message: `expected GET or POST, received ${request.method}`,
+        },
+    };
+}
+async function parseGetRequest(request, options) {
+    const compactHeader = request.headers.get(SNAP_PAYLOAD_HEADER)?.trim();
+    if (!compactHeader) {
+        return { success: true, action: { type: ACTION_TYPE_GET } };
+    }
+    const result = await validateJfsPayload({
+        jfsText: compactHeader,
+        schema: getPayloadSchema,
+        request,
+        options,
+        invalidJsonMessage: `${SNAP_PAYLOAD_HEADER} must be a valid JFS compact string`,
+    });
+    if (!result.ok) {
+        return { success: false, error: result.error };
+    }
+    return {
+        success: true,
+        action: { type: ACTION_TYPE_GET, ...result.payload },
+    };
+}
+async function parsePostRequest(request, options) {
+    const result = await validateJfsPayload({
+        jfsText: await request.text(),
+        schema: payloadSchema,
+        request,
+        options,
+    });
+    if (!result.ok) {
+        return { success: false, error: result.error };
+    }
+    const payload = result.payload;
+    if (payload.fid !== undefined && payload.fid !== payload.user.fid) {
         return {
             success: false,
             error: {
-                type: "invalid_json",
-                message: "request body is not valid JSON",
+                type: "fid_mismatch",
+                message: `fid "${payload.fid}" does not match user.fid "${payload.user.fid}"`,
             },
         };
     }
-    const parsed = requestBodySchema.safeParse(jsonBody);
-    if (!parsed.success) {
+    return {
+        success: true,
+        action: { type: ACTION_TYPE_POST, ...payload },
+    };
+}
+/**
+ * Shared pipeline for authenticated snap requests: parse the JFS envelope,
+ * decode and schema-validate the payload, optionally verify the JFS signature
+ * against an active hub signer (matching `user.fid`), then check timestamp
+ * skew and that `audience` matches the request origin.
+ *
+ * Both GET (payload header) and POST (request body) feed into this.
+ */
+async function validateJfsPayload({ jfsText, schema, request, options, invalidJsonMessage, }) {
+    const parsed = parseJfs(jfsText);
+    if (!parsed.ok) {
         return {
-            success: false,
-            error: { type: "invalid_json", message: parsed.error.message },
+            ok: false,
+            error: {
+                type: "invalid_json",
+                message: invalidJsonMessage ?? parsed.error,
+            },
         };
     }
-    const payloadParsed = payloadSchema.safeParse(decodePayload(parsed.data.payload));
+    const jfs = parsed.jfs;
+    const payloadParsed = schema.safeParse(decodePayload(jfs.payload));
     if (!payloadParsed.success) {
         return {
-            success: false,
+            ok: false,
             error: { type: "validation", issues: payloadParsed.error.issues },
         };
     }
-    const body = payloadParsed.data;
+    const payload = payloadParsed.data;
     if (!options.skipJFSVerification) {
-        const jfs = await verifyJFSRequestBody(parsed.data);
-        if (!jfs.valid) {
+        const verified = await verifyJFS(jfs);
+        if (!verified.valid) {
             return {
-                success: false,
-                error: { type: "signature", message: jfs.error.message },
+                ok: false,
+                error: { type: "signature", message: verified.error.message },
             };
         }
-        if (jfs.signingUserFid !== body.user.fid) {
+        if (verified.signingUserFid !== payload.user.fid) {
             return {
-                success: false,
+                ok: false,
                 error: {
                     type: "fid_mismatch",
-                    message: `JFS header fid "${jfs.signingUserFid}" does not match user.fid "${body.user.fid}"`,
+                    message: `JFS header fid "${verified.signingUserFid}" does not match user.fid "${payload.user.fid}"`,
                 },
             };
         }
     }
-    if (Math.abs(nowSec - body.timestamp) > maxSkew) {
+    const maxSkew = options.maxSkewSeconds ?? DEFAULT_SNAP_POST_MAX_SKEW_SECONDS;
+    const nowSec = Math.floor(Date.now() / 1000);
+    if (Math.abs(nowSec - payload.timestamp) > maxSkew) {
         return {
-            success: false,
+            ok: false,
             error: {
                 type: "replay",
                 message: `timestamp outside allowed skew of ${maxSkew}s`,
@@ -100,29 +139,14 @@ export async function parseRequest(request, options = {}) {
             // do nothing
         }
     }
-    if (expectedOrigin !== undefined && body.audience !== expectedOrigin) {
+    if (expectedOrigin !== undefined && payload.audience !== expectedOrigin) {
         return {
-            success: false,
+            ok: false,
             error: {
                 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}"`,
+                message: `payload audience "${payload.audience}" does not match expected origin "${expectedOrigin}"`,
             },
         };
     }
-    return {
-        success: true,
-        action: {
-            type: ACTION_TYPE_POST,
-            ...body,
-        },
-    };
+    return { ok: true, payload };
 }

package/dist/server/verify.d.ts

@@ -1,8 +1,15 @@
-export declare function verifyJFSRequestBody<TPayload>(requestBody: {
-    header: string;
-    payload: string;
-    signature: string;
-}, options?: {
+import { type JsonFarcasterSignature } from "@farcaster/jfs";
+/**
+ * Parse a JFS object or string into normalized form (see {@link toJsonFarcasterSignature} / `uncompact`).
+ */
+export declare function parseJfs(text: string): {
+    ok: true;
+    jfs: JsonFarcasterSignature;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function verifyJFS<TPayload>(jfs: JsonFarcasterSignature, options?: {
     hubHttpBaseUrl?: string;
 }): Promise<{
     valid: false;

package/dist/server/verify.js

@@ -1,33 +1,40 @@
-import { compact, decode, decodePayload as jfsDecodePayload, encodePayload as jfsEncodePayload, verify, } from "@farcaster/jfs";
+import { decode, decodePayload as jfsDecodePayload, encodePayload as jfsEncodePayload, toJsonFarcasterSignature, verify, } from "@farcaster/jfs";
 import { hexToBytes } from "viem";
 import { DEFAULT_SNAP_HUB_HTTP_BASE_URL, getActiveEd25519SignerKeysFromHubHttp, } from "./hubs.js";
-export async function verifyJFSRequestBody(requestBody, options = {}) {
-    let compactJfs;
+/**
+ * Parse a JFS object or string into normalized form (see {@link toJsonFarcasterSignature} / `uncompact`).
+ */
+export function parseJfs(text) {
+    const trimmed = text.trim();
+    let jfsFromJson;
     try {
-        compactJfs = compact({
-            header: requestBody.header,
-            payload: requestBody.payload,
-            signature: requestBody.signature,
-        });
+        jfsFromJson = JSON.parse(trimmed);
     }
-    catch (error) {
-        return {
-            valid: false,
-            error: error instanceof Error ? error : new Error(String(error)),
-        };
+    catch {
+        jfsFromJson = undefined;
     }
-    let decoded;
-    try {
-        decoded = decode(compactJfs);
+    if (jfsFromJson !== undefined && isJfsObject(jfsFromJson)) {
+        return { ok: true, jfs: jfsFromJson };
     }
-    catch (error) {
+    const jfsFromString = tryUncompactJfsString(trimmed);
+    if (jfsFromString) {
+        return { ok: true, jfs: jfsFromString };
+    }
+    return {
+        ok: false,
+        error: "invalid JFS envelope: must be JSON with header, payload, and signature fields, or a JFS compact string (three dot-separated segments)",
+    };
+}
+export async function verifyJFS(jfs, options = {}) {
+    const decoded = tryDecodeJfs(jfs);
+    if (!decoded) {
         return {
             valid: false,
-            error: error instanceof Error ? error : new Error(String(error)),
+            error: new Error("invalid JFS envelope"),
         };
     }
     try {
-        await verify({ data: compactJfs, strict: true, keyTypes: ["app_key"] });
+        await verify({ data: jfs, strict: true, keyTypes: ["app_key"] });
     }
     catch (error) {
         return {
@@ -35,6 +42,12 @@ export async function verifyJFSRequestBody(requestBody, options = {}) {
             error: error instanceof Error ? error : new Error(String(error)),
         };
     }
+    return hubVerifyDecodedPayload(decoded, options);
+}
+/**
+ * Verify that the signing key for a JFS payload is an active signer for the FID.
+ */
+async function hubVerifyDecodedPayload(decoded, options) {
     const { header, payload } = decoded;
     const keys = await getActiveEd25519SignerKeysFromHubHttp(options.hubHttpBaseUrl ?? DEFAULT_SNAP_HUB_HTTP_BASE_URL, header.fid);
     if (!keys.ok) {
@@ -78,6 +91,41 @@ export function decodePayload(payload) {
 export function encodePayload(payload) {
     return jfsEncodePayload(payload);
 }
+/**
+ * Normalize a compact JFS string to `{ header, payload, signature }` using
+ * `@farcaster/jfs` {@link toJsonFarcasterSignature} (which delegates to `uncompact` for strings).
+ * Returns null if the string is malformed.
+ */
+function tryUncompactJfsString(value) {
+    try {
+        return toJsonFarcasterSignature(value.trim());
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fully decode a JFS envelope or compact string via `@farcaster/jfs` {@link decode}:
+ * parsed header object, parsed payload, signature bytes.
+ */
+function tryDecodeJfs(input) {
+    try {
+        return decode(input);
+    }
+    catch {
+        return null;
+    }
+}
+function isJfsObject(v) {
+    return (v !== null &&
+        typeof v === "object" &&
+        "header" in v &&
+        typeof v.header === "string" &&
+        "payload" in v &&
+        typeof v.payload === "string" &&
+        "signature" in v &&
+        typeof v.signature === "string");
+}
 function bytesEqual(a, b) {
     if (a.length !== b.length)
         return false;

package/dist/ui/catalog.d.ts

@@ -380,7 +380,7 @@ export declare const snapJsonRenderCatalog: import("@json-render/core").Catalog<
                 cells: z.ZodArray<z.ZodObject<{
                     row: z.ZodNumber;
                     col: z.ZodNumber;
-                    color: z.ZodOptional<z.ZodEnum<{
+                    color: z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodUnion<readonly [z.ZodEnum<{
                         gray: "gray";
                         blue: "blue";
                         red: "red";
@@ -389,7 +389,7 @@ export declare const snapJsonRenderCatalog: import("@json-render/core").Catalog<
                         teal: "teal";
                         purple: "purple";
                         pink: "pink";
-                    }>>;
+                    }>, z.ZodString]>>>;
                     content: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>>;
                 gap: z.ZodOptional<z.ZodEnum<{

package/dist/ui/catalog.js

@@ -90,7 +90,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
         },
         cell_grid: {
             props: cellGridProps,
-            description: "Cell grid — sparse colored cells on a rows×cols grid. Two interaction modes: leave select 'off' and bind on.press to fire an action per cell press (inputs[name] is the pressed 'row,col' before the action runs); or set select 'single'/'multiple' for press-to-select with a visual ring (no auto-fire — pair with a separate submit button). on.press is ignored when select is on.",
+            description: "Cell grid — sparse colored cells on a rows×cols grid. Cell color is a palette name or literal #rrggbb hex (hex ignores page accent). Two interaction modes: leave select 'off' and bind on.press to fire an action per cell press (inputs[name] is the pressed 'row,col' before the action runs); or set select 'single'/'multiple' for press-to-select with a visual ring (no auto-fire — pair with a separate submit button). on.press is ignored when select is on.",
         },
     },
     actions: {