@farcaster/snap 2.0.0 → 2.0.2

package/src/ui/cell-grid.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { PALETTE_COLOR_VALUES } from "../colors.js";
+import {
+  GRID_MIN_COLS,
+  GRID_MAX_COLS,
+  GRID_MIN_ROWS,
+  GRID_MAX_ROWS,
+  GRID_GAP_VALUES,
+} from "../constants.js";
+
+const cellGridCellSchema = z.object({
+  row: z.number().int().nonnegative(),
+  col: z.number().int().nonnegative(),
+  color: z.enum(PALETTE_COLOR_VALUES).optional(),
+  content: z.string().optional(),
+});
+
+export const cellGridProps = z
+  .object({
+    name: z.string().min(1).optional(),
+    cols: z.number().int().min(GRID_MIN_COLS).max(GRID_MAX_COLS),
+    rows: z.number().int().min(GRID_MIN_ROWS).max(GRID_MAX_ROWS),
+    cells: z.array(cellGridCellSchema),
+    gap: z.enum(GRID_GAP_VALUES).optional(),
+    rowHeight: z.number().int().min(8).max(64).optional(),
+    select: z.enum(["off", "single", "multiple"]).optional(),
+  })
+  .superRefine((val, ctx) => {
+    const { cols, rows, cells } = val;
+    for (let i = 0; i < cells.length; i++) {
+      const c = cells[i]!;
+      if (c.row < 0 || c.row >= rows) {
+        ctx.addIssue({
+          code: "custom",
+          message: `cell_grid cell row ${c.row} out of bounds (0–${rows - 1})`,
+          path: ["cells", i, "row"],
+        });
+      }
+      if (c.col < 0 || c.col >= cols) {
+        ctx.addIssue({
+          code: "custom",
+          message: `cell_grid cell col ${c.col} out of bounds (0–${cols - 1})`,
+          path: ["cells", i, "col"],
+        });
+      }
+    }
+  });
+
+export type CellGridProps = z.infer<typeof cellGridProps>;

package/src/ui/image.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 
-export const IMAGE_ASPECTS = ["1:1", "16:9", "4:3", "3:4", "9:16"] as const;
+export const IMAGE_ASPECTS = ["1:1", "16:9", "4:3", "9:16"] as const;
 
 export const imageProps = z.object({
   url: z.string(),

package/src/ui/index.ts

@@ -42,3 +42,9 @@ export type { StackProps } from "./stack.js";
 
 export { textProps } from "./text.js";
 export type { TextProps } from "./text.js";
+
+export { barChartProps } from "./bar-chart.js";
+export type { BarChartProps } from "./bar-chart.js";
+
+export { cellGridProps } from "./cell-grid.js";
+export type { CellGridProps } from "./cell-grid.js";

package/src/ui/item.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 
-export const ITEM_VARIANTS = ["default", "outline", "muted"] as const;
+export const ITEM_VARIANTS = ["default"] as const;
 export const ITEM_MAX_TITLE_CHARS = 100;
 export const ITEM_MAX_DESCRIPTION_CHARS = 160;
 

package/src/ui/schema.ts

@@ -11,7 +11,7 @@ export const snapJsonRenderSchema = defineSchema(
       elements: s.record(
         s.object({
           type: s.ref("catalog.components"),
-          props: s.propsOf("catalog.components"),
+          props: { ...s.propsOf("catalog.components"), optional: true },
           children: { ...s.array(s.string()), optional: true },
         }),
       ),
@@ -30,7 +30,7 @@ export const snapJsonRenderSchema = defineSchema(
   {
     defaultRules: [
       "You are generating auxiliary UI for a Farcaster Snap. Prefer components matching snap element types (Item, Badge, ButtonGroup, Input, Switch, ToggleGroup, Slider, Progress, Image, Separator).",
-      "Snap pages use a Stack root with at most 6 body children and 1 media element (Image); keep generated trees small.",
+      "Snap structural limits: max 64 elements, max 7 children on root, max 6 children per non-root container, max 4 levels of nesting. Keep generated trees small.",
       "Bottom-of-card snap buttons are Button components; use actions post / link / mini_app / sdk per SPEC.md.",
     ],
   },

package/src/ui/slider.ts

@@ -12,6 +12,8 @@ export const sliderProps = z
     step: z.number().optional(),
     defaultValue: z.number().optional(),
     label: z.string().max(SLIDER_MAX_LABEL_CHARS).optional(),
+    /** When true, display the current value next to the label. */
+    showValue: z.boolean().optional(),
   })
   .superRefine((val, ctx) => {
     if (val.min > val.max) {

package/src/ui/text.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 
-export const TEXT_SIZES = ["lg", "md", "sm"] as const;
-export const TEXT_WEIGHTS = ["bold", "medium", "normal"] as const;
+export const TEXT_SIZES = ["md", "sm"] as const;
+export const TEXT_WEIGHTS = ["bold", "normal"] as const;
 export const TEXT_ALIGNS = ["left", "center", "right"] as const;
 export const TEXT_MAX_CONTENT_CHARS = 320;
 

package/src/validator.ts

@@ -1,15 +1,231 @@
 import { z } from "zod";
 import { snapResponseSchema } from "./schemas";
+import { MAX_CHILDREN, MAX_DEPTH, MAX_ELEMENTS, MAX_ROOT_CHILDREN, SPEC_VERSION_1 } from "./constants";
+import { snapJsonRenderCatalog } from "./ui/catalog.js";
 
 export type ValidationResult = {
   valid: boolean;
   issues: z.core.$ZodIssue[];
 };
 
+// ─── Helpers ──────────────────────────────────────────
+
+/** Actions whose `params.target` must be a valid URL. */
+const URL_TARGET_ACTIONS = new Set([
+  "submit",
+  "open_url",
+  "open_snap",
+  "open_mini_app",
+]);
+
+/** Image file extensions allowed in image URLs. */
+const ALLOWED_IMAGE_EXTENSIONS = new Set(["jpg", "jpeg", "png", "gif", "webp"]);
+
+/**
+ * Returns true if the URL is a loopback address (localhost dev exception).
+ */
+function isLoopback(url: URL): boolean {
+  const host = url.hostname;
+  return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]";
+}
+
+/**
+ * Validate a URL string: must be HTTPS (or HTTP on loopback for dev).
+ * Returns an error message or null if valid.
+ */
+function validateUrl(raw: string): string | null {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return `Invalid URL: "${raw}"`;
+  }
+
+  if (url.protocol === "https:") return null;
+  if (url.protocol === "http:" && isLoopback(url)) return null;
+  if (url.protocol === "javascript:") return `javascript: URIs are not allowed`;
+
+  return `URL must use HTTPS (got ${url.protocol.replace(":", "")}): "${raw}"`;
+}
+
+/**
+ * Validate an image URL: must pass URL validation + have an allowed extension.
+ */
+function validateImageUrl(raw: string): string | null {
+  const urlError = validateUrl(raw);
+  if (urlError) return urlError;
+
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return null; // already caught above
+  }
+
+  const pathname = url.pathname;
+  const lastDot = pathname.lastIndexOf(".");
+  if (lastDot === -1) {
+    return `Image URL must end with a supported extension (${[...ALLOWED_IMAGE_EXTENSIONS].join(", ")}): "${raw}"`;
+  }
+
+  const ext = pathname.slice(lastDot + 1).toLowerCase();
+  if (!ALLOWED_IMAGE_EXTENSIONS.has(ext)) {
+    return `Image URL has unsupported extension ".${ext}" (allowed: ${[...ALLOWED_IMAGE_EXTENSIONS].join(", ")}): "${raw}"`;
+  }
+
+  return null;
+}
+
+// ─── Depth measurement ────────────────────────────────
+
 /**
- * Validates a snap response against the schema.
+ * Walk the element tree from `root` and return the max depth reached.
+ * Avoids infinite loops by tracking visited element ids.
+ */
+function measureDepth(
+  elements: Record<string, { children?: string[] }>,
+  id: string,
+  visited: Set<string> = new Set(),
+): number {
+  if (visited.has(id)) return 0;
+  visited.add(id);
+
+  const el = elements[id];
+  if (!el?.children?.length) return 1;
+
+  let max = 0;
+  for (const childId of el.children) {
+    max = Math.max(max, measureDepth(elements, childId, visited));
+  }
+  return 1 + max;
+}
+
+// ─── Element types for traversal ──────────────────────
+
+type ElementShape = {
+  type?: string;
+  children?: string[];
+  props?: Record<string, unknown>;
+  on?: Record<string, { action?: string; params?: Record<string, unknown> }>;
+};
+
+// ─── Structural validation ────────────────────────────
+
+/**
+ * Validate structural constraints on the snap UI tree:
+ * - root must reference an existing element
+ * - Total element count ≤ MAX_ELEMENTS
+ * - Children per element ≤ MAX_CHILDREN
+ * - Nesting depth ≤ MAX_DEPTH
+ */
+function validateStructure(
+  ui: { root: string; elements: Record<string, unknown> },
+): z.core.$ZodIssue[] {
+  const issues: z.core.$ZodIssue[] = [];
+  const elements = ui.elements as Record<string, ElementShape>;
+
+  const elementCount = Object.keys(elements).length;
+  if (elementCount > MAX_ELEMENTS) {
+    issues.push({
+      code: "custom",
+      message: `Snap exceeds maximum of ${MAX_ELEMENTS} elements (found ${elementCount})`,
+      path: ["ui", "elements"],
+    });
+  }
+
+  // Root element has a stricter children limit
+  const rootEl = elements[ui.root];
+  if (rootEl?.children && rootEl.children.length > MAX_ROOT_CHILDREN) {
+    issues.push({
+      code: "custom",
+      message: `Root element "${ui.root}" exceeds maximum of ${MAX_ROOT_CHILDREN} children (found ${rootEl.children.length})`,
+      path: ["ui", "elements", ui.root, "children"],
+    });
+  }
+
+  for (const [id, el] of Object.entries(elements)) {
+    if (id === ui.root) continue; // already checked above
+    if (el.children && el.children.length > MAX_CHILDREN) {
+      issues.push({
+        code: "custom",
+        message: `Element "${id}" exceeds maximum of ${MAX_CHILDREN} children (found ${el.children.length})`,
+        path: ["ui", "elements", id, "children"],
+      });
+    }
+  }
+
+  const depth = measureDepth(
+    elements as Record<string, { children?: string[] }>,
+    ui.root,
+  );
+  if (depth > MAX_DEPTH) {
+    issues.push({
+      code: "custom",
+      message: `Snap exceeds maximum nesting depth of ${MAX_DEPTH} (found ${depth})`,
+      path: ["ui", "root"],
+    });
+  }
+
+  return issues;
+}
+
+// ─── URL validation ───────────────────────────────────
+
+/**
+ * Validate all URLs in the snap:
+ * - image.url: must be HTTPS with allowed extension
+ * - action target URLs (submit, open_url, open_snap, open_mini_app): must be HTTPS
+ */
+function validateUrls(
+  elements: Record<string, unknown>,
+): z.core.$ZodIssue[] {
+  const issues: z.core.$ZodIssue[] = [];
+  const els = elements as Record<string, ElementShape>;
+
+  for (const [id, el] of Object.entries(els)) {
+    // Validate image URLs
+    if (el.type === "image" && typeof el.props?.url === "string") {
+      const error = validateImageUrl(el.props.url);
+      if (error) {
+        issues.push({
+          code: "custom",
+          message: error,
+          path: ["ui", "elements", id, "props", "url"],
+        });
+      }
+    }
+
+    // Validate action target URLs
+    if (el.on) {
+      for (const [event, binding] of Object.entries(el.on)) {
+        if (
+          binding &&
+          URL_TARGET_ACTIONS.has(binding.action ?? "") &&
+          typeof binding.params?.target === "string"
+        ) {
+          const error = validateUrl(binding.params.target);
+          if (error) {
+            issues.push({
+              code: "custom",
+              message: error,
+              path: ["ui", "elements", id, "on", event, "params", "target"],
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return issues;
+}
+
+// ─── Public API ───────────────────────────────────────
+
+/**
+ * Validates a snap response against the schema, structural constraints, and URL rules.
  * Element-level prop validation is handled by the json-render catalog.
- * This validates the snap envelope (version, theme, effects, spec shape).
+ * This validates the snap envelope (version, theme, effects, spec shape)
+ * and enforces structural limits (element count, children, depth) and URL validation.
  */
 export function validateSnapResponse(json: unknown): ValidationResult {
   const parsed = snapResponseSchema.safeParse(json);
@@ -19,5 +235,38 @@ export function validateSnapResponse(json: unknown): ValidationResult {
       issues: parsed.error.issues,
     };
   }
+
+  const ui = parsed.data.ui;
+
+  // Root reference check applies to all versions
+  if (!(ui.root in ui.elements)) {
+    return {
+      valid: false,
+      issues: [{
+        code: "custom",
+        message: `ui.root "${ui.root}" does not exist in ui.elements`,
+        path: ["ui", "root"],
+      }],
+    };
+  }
+
+  // Structural limits and URL validation only apply to v2+ snaps
+  if (parsed.data.version !== SPEC_VERSION_1) {
+    const structuralIssues = validateStructure(ui);
+    if (structuralIssues.length > 0) {
+      return { valid: false, issues: structuralIssues };
+    }
+
+    const urlIssues = validateUrls(ui.elements);
+    if (urlIssues.length > 0) {
+      return { valid: false, issues: urlIssues };
+    }
+
+    const catalogResult = snapJsonRenderCatalog.validate(ui);
+    if (!catalogResult.success) {
+      return { valid: false, issues: catalogResult.error?.issues ?? [] };
+    }
+  }
+
   return { valid: true, issues: [] };
 }

package/dist/dataStore.d.ts

@@ -1,12 +0,0 @@
-export type DataStoreValue = string | number | boolean | null | DataStoreValue[] | {
-    [key: string]: DataStoreValue;
-};
-export type SnapDataStoreOperations = {
-    get(key: string): Promise<DataStoreValue | null>;
-    set(key: string, value: DataStoreValue): Promise<void>;
-};
-export type SnapDataStore = SnapDataStoreOperations & {
-    withLock<T>(fn: (store: SnapDataStoreOperations) => Promise<T>): Promise<T>;
-};
-export declare function createDefaultDataStore(): SnapDataStore;
-export declare function createInMemoryDataStore(): SnapDataStore;

package/dist/dataStore.js

@@ -1,35 +0,0 @@
-export function createDefaultDataStore() {
-    const err = new Error("Data store is not configured. Use withUpstash() from @farcaster/snap-upstash or provide a data store implementation.");
-    return {
-        get(_key) {
-            return Promise.reject(err);
-        },
-        set(_key, _value) {
-            return Promise.reject(err);
-        },
-        withLock(_fn) {
-            return Promise.reject(err);
-        },
-    };
-}
-export function createInMemoryDataStore() {
-    const data = new Map();
-    const ops = {
-        get: async (key) => {
-            return data.get(key) ?? null;
-        },
-        set: async (key, value) => {
-            data.set(key, value);
-        },
-    };
-    /** Serializes `withLock` callbacks so async work does not interleave across callers. */
-    let lockChain = Promise.resolve();
-    return {
-        ...ops,
-        withLock(fn) {
-            const run = lockChain.then(() => fn(ops));
-            lockChain = run.then(() => undefined, () => undefined);
-            return run;
-        },
-    };
-}

package/dist/middleware.d.ts

@@ -1,3 +0,0 @@
-import { SnapFunction } from "./schemas.js";
-export type Middleware = (fn: SnapFunction) => SnapFunction;
-export declare function useMiddleware(fn: SnapFunction, middleware: Middleware[]): SnapFunction;

package/dist/middleware.js

@@ -1,3 +0,0 @@
-export function useMiddleware(fn, middleware) {
-    return middleware.reduce((acc, middleware) => middleware(acc), fn);
-}

package/dist/react/hooks/use-snap-accent.d.ts

@@ -1,13 +0,0 @@
-import { type CSSProperties } from "react";
-import type { PaletteColor } from "@farcaster/snap";
-/**
- * CSS variables so Neynar controls (`bg-primary`, `data-checked:bg-primary`, etc.)
- * use the snap `theme.accent` inside json-render catalog components.
- */
-export declare function useSnapAccentScopeStyle(): CSSProperties;
-/** Active snap palette table for the current docs shell theme. */
-export declare function useSnapPalette(): {
-    hex: (name: string) => string;
-    map: Record<PaletteColor, string>;
-    theme: "light" | "dark";
-};

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

@@ -1,32 +0,0 @@
-"use client";
-import { useMemo } from "react";
-import { useStateStore } from "@json-render/react";
-import { PALETTE_DARK_HEX, PALETTE_LIGHT_HEX } from "@farcaster/snap";
-import { useColorMode } from "@neynar/ui/color-mode";
-import { resolveSnapPaletteHex } from "../lib/resolve-palette-hex.js";
-import { snapPreviewPrimaryCssProperties } from "../lib/preview-primary-css.js";
-import { useSnapPreviewPageAccent } from "../accent-context.js";
-/**
- * CSS variables so Neynar controls (`bg-primary`, `data-checked:bg-primary`, etc.)
- * use the snap `theme.accent` inside json-render catalog components.
- */
-export function useSnapAccentScopeStyle() {
-    const { get } = useStateStore();
-    const { mode } = useColorMode();
-    const pageAccent = useSnapPreviewPageAccent();
-    const fromState = get("/theme/accent");
-    const accentRaw = (typeof pageAccent === "string" && pageAccent.length > 0
-        ? pageAccent
-        : fromState) ?? undefined;
-    const accentName = typeof accentRaw === "string" && accentRaw.length > 0
-        ? accentRaw
-        : "purple";
-    return useMemo(() => snapPreviewPrimaryCssProperties(accentName, mode), [accentName, mode]);
-}
-/** Active snap palette table for the current docs shell theme. */
-export function useSnapPalette() {
-    const { mode } = useColorMode();
-    const map = mode === "dark" ? PALETTE_DARK_HEX : PALETTE_LIGHT_HEX;
-    const hex = (name) => resolveSnapPaletteHex(name, mode);
-    return { hex, map, theme: mode };
-}

package/src/dataStore.ts

@@ -1,62 +0,0 @@
-export type DataStoreValue =
-  | string
-  | number
-  | boolean
-  | null
-  | DataStoreValue[]
-  | { [key: string]: DataStoreValue };
-
-export type SnapDataStoreOperations = {
-  get(key: string): Promise<DataStoreValue | null>;
-  set(key: string, value: DataStoreValue): Promise<void>;
-};
-
-export type SnapDataStore = SnapDataStoreOperations & {
-  withLock<T>(fn: (store: SnapDataStoreOperations) => Promise<T>): Promise<T>;
-};
-
-export function createDefaultDataStore(): SnapDataStore {
-  const err = new Error(
-    "Data store is not configured. Use withUpstash() from @farcaster/snap-upstash or provide a data store implementation.",
-  );
-  return {
-    get(_key: string): Promise<never> {
-      return Promise.reject(err);
-    },
-    set(_key: string, _value: DataStoreValue): Promise<never> {
-      return Promise.reject(err);
-    },
-    withLock<T>(
-      _fn: (store: SnapDataStoreOperations) => Promise<T>,
-    ): Promise<never> {
-      return Promise.reject(err);
-    },
-  };
-}
-
-export function createInMemoryDataStore(): SnapDataStore {
-  const data = new Map<string, DataStoreValue>();
-  const ops: SnapDataStoreOperations = {
-    get: async (key: string): Promise<DataStoreValue | null> => {
-      return data.get(key) ?? null;
-    },
-    set: async (key: string, value: DataStoreValue): Promise<void> => {
-      data.set(key, value);
-    },
-  };
-  /** Serializes `withLock` callbacks so async work does not interleave across callers. */
-  let lockChain: Promise<unknown> = Promise.resolve();
-  return {
-    ...ops,
-    withLock<T>(
-      fn: (store: SnapDataStoreOperations) => Promise<T>,
-    ): Promise<T> {
-      const run = lockChain.then(() => fn(ops));
-      lockChain = run.then(
-        () => undefined,
-        () => undefined,
-      );
-      return run;
-    },
-  };
-}

package/src/middleware.ts

@@ -1,7 +0,0 @@
-import { SnapFunction } from "./schemas";
-
-export type Middleware = (fn: SnapFunction) => SnapFunction;
-
-export function useMiddleware(fn: SnapFunction, middleware: Middleware[]) {
-  return middleware.reduce((acc, middleware) => middleware(acc), fn);
-}

package/src/react/hooks/use-snap-accent.ts

@@ -1,45 +0,0 @@
-"use client";
-
-import { useMemo, type CSSProperties } from "react";
-import { useStateStore } from "@json-render/react";
-import type { PaletteColor } from "@farcaster/snap";
-import { PALETTE_DARK_HEX, PALETTE_LIGHT_HEX } from "@farcaster/snap";
-import { useColorMode } from "@neynar/ui/color-mode";
-import { resolveSnapPaletteHex } from "../lib/resolve-palette-hex";
-import { snapPreviewPrimaryCssProperties } from "../lib/preview-primary-css";
-import { useSnapPreviewPageAccent } from "../accent-context";
-
-/**
- * CSS variables so Neynar controls (`bg-primary`, `data-checked:bg-primary`, etc.)
- * use the snap `theme.accent` inside json-render catalog components.
- */
-export function useSnapAccentScopeStyle(): CSSProperties {
-  const { get } = useStateStore();
-  const { mode } = useColorMode();
-  const pageAccent = useSnapPreviewPageAccent();
-  const fromState = get("/theme/accent");
-  const accentRaw =
-    (typeof pageAccent === "string" && pageAccent.length > 0
-      ? pageAccent
-      : fromState) ?? undefined;
-  const accentName =
-    typeof accentRaw === "string" && accentRaw.length > 0
-      ? accentRaw
-      : "purple";
-  return useMemo(
-    () => snapPreviewPrimaryCssProperties(accentName, mode),
-    [accentName, mode],
-  );
-}
-
-/** Active snap palette table for the current docs shell theme. */
-export function useSnapPalette(): {
-  hex: (name: string) => string;
-  map: Record<PaletteColor, string>;
-  theme: "light" | "dark";
-} {
-  const { mode } = useColorMode();
-  const map = mode === "dark" ? PALETTE_DARK_HEX : PALETTE_LIGHT_HEX;
-  const hex = (name: string) => resolveSnapPaletteHex(name, mode);
-  return { hex, map, theme: mode };
-}