@farcaster/snap 2.1.1 → 2.2.0

package/dist/verify.test.js

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { verifyJFSRequestBody } from "./server/verify.js";
+import { verifyJFS } from "./server/verify.js";
 const validRequestBody = `{
   "header":"eyJmaWQiOjI2MTMxOSwidHlwZSI6ImFwcF9rZXkiLCJrZXkiOiIweGY0ZGQyNjczYTUzMjEwYzQ3ZGYzZjFmNTk0NjZlZTdhMTM3ZmQxOGQ5NTVjMmU2OGExMmQwOTE2MGE2NmMyMTUifQ",
   "payload":"eyJmaWQiOjI2MTMxOSwiaW5wdXRzIjp7ImRpc3BsYXkiOiJJU08gKFVUQykifSwiYnV0dG9uX2luZGV4IjowLCJ0aW1lc3RhbXAiOjE3NzQ2OTMyMTN9",
@@ -7,7 +7,7 @@ const validRequestBody = `{
 }`;
 /** Matches JFS header `key` (Ed25519 public key, 32 bytes hex without `0x` in hub JSON field). */
 const HUB_SIGNER_KEY_HEX = "f4dd2673a53210c47df3f1f59466ee7a137fd18d955c2e68a12d09160a66c215";
-describe("verifyJFSRequestBody", () => {
+describe("verifyJFS", () => {
     beforeEach(() => {
         vi.stubGlobal("fetch", vi.fn(async (input) => {
             const u = String(input);
@@ -41,7 +41,7 @@ describe("verifyJFSRequestBody", () => {
         vi.unstubAllGlobals();
     });
     it("accepts JSON JFS body and verifies crypto + hub signer list", async () => {
-        const result = await verifyJFSRequestBody(JSON.parse(validRequestBody));
+        const result = await verifyJFS(JSON.parse(validRequestBody));
         expect(result.valid).toBe(true);
         if (result.valid) {
             expect(result.data).toEqual({

package/llms.txt

@@ -37,7 +37,7 @@ Top-level fields: `version` (required, `"1.0"` or `"2.0"`), `theme` (optional, `
 | Total elements | Max **64** in `ui.elements` |
 | Root children | Max **7** children on the root element |
 | Children per element | Max **6** per non-root container (`stack`, `item_group`) |
-| Nesting depth | Max **4** levels from root to deepest leaf |
+| Nesting depth | Max **5** levels from root to deepest leaf |
 
 ## Components (16 total)
 
@@ -95,7 +95,7 @@ Top-level fields: `version` (required, `"1.0"` or `"2.0"`), `theme` (optional, `
 - `name` (string, optional): POST inputs key. Default: `"grid_tap"`
 - `cols` (number, required, 2–32)
 - `rows` (number, required, 2–16)
-- `cells` (array, required): sparse list of `{ row, col, color?: PaletteColor, content?: string }`
+- `cells` (array, required): sparse list of `{ row, col, color?: PaletteColor | #rrggbb, content?: string }`
 - `gap` (optional): `"none"` (0px) | `"sm"` (1px) | `"md"` (2px) | `"lg"` (4px). Default: `"sm"`
 - `rowHeight` (number, optional, 8–64): pixel height per row. Default: 28. Grid height = rows × rowHeight
 - `select` (optional): `"off"` | `"single"` | `"multiple"`. Default: `"off"`. With `select: "off"`, bind `on.press` for press-to-act (each press writes `"row,col"` to `inputs[name]` and fires the action). With `"single"` / `"multiple"`, presses accumulate selection state and pair with a separate submit `button`; `on.press` is ignored.
@@ -107,6 +107,7 @@ Top-level fields: `version` (required, `"1.0"` or `"2.0"`), `theme` (optional, `
 - `direction` (optional): `"vertical"` | `"horizontal"`. Default: `"vertical"`
 - `gap` (optional): `"none"` | `"sm"` | `"md"` | `"lg"`. Default: `"md"`
 - `justify` (optional): `"start"` | `"center"` | `"end"` | `"between"` | `"around"`
+- `columns` (optional, horizontal only): `2`–`6` — CSS grid with equal columns (mixed children or layout that needs fixed column counts).
 - Children are element IDs
 
 **item_group** — Groups item children.
@@ -171,6 +172,16 @@ Bound to buttons via `on.press`:
 | `send_token` | `token`, `amount?`, `recipientFid?`, `recipientAddress?` | Send token flow |
 | `swap_token` | `sellToken?`, `buyToken?` | Swap token flow |
 
+## Authenticated requests
+
+POST requests carry a JFS envelope (JSON object **or** compact dot-separated string). `parseRequest` validates the payload and (unless `skipJFSVerification`) cryptographically verifies the JFS against an active hub signer for `user.fid`. On the server, `ctx.action.user.fid` is **always present and verified** for `type === "post"`.
+
+GET requests MAY include optional viewer identity in the `X-Snap-Payload` request header (a JFS compact string with the same shape as POST minus `inputs` and `fid`). When present and valid, `ctx.action` on GET MAY include `user`, `timestamp`, `audience`, and `surface`.
+
+`ctx.action.user` on GET is **best-effort and never guaranteed** — older or custom clients, cache layers, crawlers, and `curl` may yield an anonymous GET even for users who have POSTed to this snap before. Always render a working anonymous first load; treat viewer fields on GET as a strict enhancement. `parseRequest` (and `@farcaster/snap-hono`'s GET handler) silently fall back to anonymous `{ type: "get" }` when `X-Snap-Payload` is missing or invalid.
+
+When responses depend on viewer identity, send `Vary: Accept, X-Snap-Payload` and consider `Cache-Control: private` so caches don't serve viewer-specific bodies to other viewers (`@farcaster/snap-hono` sets `Vary` automatically).
+
 ## Icon Names (34)
 
 `arrow-right`, `arrow-left`, `external-link`, `chevron-right`, `check`, `x`, `alert-triangle`, `info`, `clock`, `heart`, `message-circle`, `repeat`, `share`, `user`, `users`, `star`, `trophy`, `zap`, `flame`, `gift`, `image`, `play`, `pause`, `wallet`, `coins`, `plus`, `minus`, `refresh-cw`, `bookmark`, `thumbs-up`, `thumbs-down`, `trending-up`, `trending-down`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farcaster/snap",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Farcaster Snaps 🫰",
   "repository": {
     "type": "git",

package/src/colors.ts

@@ -38,6 +38,33 @@ export const PALETTE_COLOR_VALUES = [
 
 export type PaletteColor = (typeof PALETTE_COLOR_VALUES)[number];
 
+/** 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: string): boolean {
+  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: string | undefined,
+  opts: { accentHex: string; appearance: "light" | "dark" },
+): string {
+  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 as PaletteColor];
+  }
+  return opts.accentHex;
+}
+
 /** Light-mode hex for each palette color (emulator / reference client). */
 export const PALETTE_LIGHT_HEX: Record<PaletteColor, string> = {
   gray: "#6E6A86",

package/src/constants.ts

@@ -1,9 +1,14 @@
 export const SPEC_VERSION_1 = "1.0" as const;
 export const SPEC_VERSION_2 = "2.0" as const;
 export const SPEC_VERSION = SPEC_VERSION_2;
-export const SUPPORTED_SPEC_VERSIONS = [SPEC_VERSION_1, SPEC_VERSION_2] as const;
+export const SUPPORTED_SPEC_VERSIONS = [
+  SPEC_VERSION_1,
+  SPEC_VERSION_2,
+] as const;
 export type SpecVersion = (typeof SUPPORTED_SPEC_VERSIONS)[number];
 
+export const SNAP_PAYLOAD_HEADER = "X-Snap-Payload" as const;
+
 export const MEDIA_TYPE = "application/vnd.farcaster.snap+json" as const;
 
 export const EFFECT_VALUES = ["confetti"] as const;
@@ -20,7 +25,8 @@ export const GRID_GAP_VALUES = ["none", "sm", "md", "lg"] as const;
 export const MAX_ELEMENTS = 64;
 export const MAX_ROOT_CHILDREN = 7;
 export const MAX_CHILDREN = 6;
-export const MAX_DEPTH = 4;
+/** Enough depth for side-by-side columns that contain labeled horizontal icon rows (pair → column → row → icon). */
+export const MAX_DEPTH = 5;
 
 // ─── Bar chart ─────────────────────────────────────────
 export const BAR_CHART_MAX_BARS = 6;

package/src/index.ts

@@ -8,6 +8,7 @@ export {
   SPEC_VERSION_2,
   SUPPORTED_SPEC_VERSIONS,
   type SpecVersion,
+  SNAP_PAYLOAD_HEADER,
   MEDIA_TYPE,
   EFFECT_VALUES,
   POST_GRID_TAP_KEY,
@@ -23,6 +24,8 @@ export {
   PALETTE_COLOR_VALUES,
   PALETTE_LIGHT_HEX,
   PALETTE_DARK_HEX,
+  isSnapHexColorString,
+  resolveSnapColorHex,
   type PaletteColor,
 } from "./colors";
 export {
@@ -30,7 +33,9 @@ export {
   ACTION_TYPE_POST,
   snapResponseSchema,
   payloadSchema,
+  getPayloadSchema,
   type SnapAction,
+  type SnapGetAction,
   type SnapContext,
   type SnapResponse,
   type SnapHandlerResult,
@@ -38,5 +43,6 @@ export {
   type SnapSpecInput,
   type SnapFunction,
   type SnapPayload,
+  type SnapGetPayload,
 } from "./schemas";
 export { validateSnapResponse, type ValidationResult } from "./validator";

package/src/react/components/cell-grid.tsx

@@ -64,12 +64,16 @@ export function SnapCellGrid({
     });
   }
 
+  /** Cells without a palette `color` — subtle fill so empty slots read as tiles. */
+  const emptyCellBg =
+    colors.mode === "dark" ? "rgba(255, 255, 255, 0.05)" : "rgba(0, 0, 0, 0.05)";
+
   const cellEls: ReactNode[] = [];
   for (let r = 0; r < rows; r++) {
     for (let c = 0; c < cols; c++) {
       const cell = cellMap.get(`${r},${c}`);
       const selected = interactive && isSelected(r, c);
-      const bg = cell?.color ? colors.colorHex(cell.color) : "transparent";
+      const bg = cell?.color ? colors.colorHex(cell.color) : emptyCellBg;
 
       cellEls.push(
         <div
@@ -105,30 +109,19 @@ export function SnapCellGrid({
     }
   }
 
-  const selectionLabel = isSelectable && selectedSet.size > 0
-    ? `inputs.${name}: ${[...selectedSet].join(isMultiple ? " | " : "")}`
-    : null;
-
   return (
-    <div>
-      <div
-        style={{
-          display: "grid",
-          width: "100%",
-          gridTemplateColumns: `repeat(${cols}, 1fr)`,
-          gap: gapPx,
-          padding: 4,
-          borderRadius: 8,
-          backgroundColor: colors.muted,
-        }}
-      >
-        {cellEls}
-      </div>
-      {selectionLabel && (
-        <div className="mt-1.5 truncate text-xs font-mono" style={{ color: colors.textMuted }}>
-          {selectionLabel}
-        </div>
-      )}
+    <div
+      style={{
+        display: "grid",
+        width: "100%",
+        gridTemplateColumns: `repeat(${cols}, 1fr)`,
+        gap: gapPx,
+        padding: 4,
+        borderRadius: 8,
+        backgroundColor: colors.muted,
+      }}
+    >
+      {cellEls}
     </div>
   );
 }

package/src/react/components/image.tsx

@@ -1,6 +1,8 @@
 "use client";
 
 import { AspectRatio } from "@neynar/ui/aspect-ratio";
+import { cn } from "@neynar/ui/utils";
+import { useSnapStackDirection } from "../stack-direction-context";
 
 function aspectToRatio(aspect: string): number {
   const [w, h] = aspect.split(":").map(Number);
@@ -16,11 +18,16 @@ export function SnapImage({
   const url = String(props.url ?? "");
   const alt = String(props.alt ?? "");
   const ratio = aspectToRatio(String(props.aspect ?? "1:1"));
+  const stackDir = useSnapStackDirection();
+  const inHorizontalStack = stackDir === "horizontal";
 
   return (
     <AspectRatio
       ratio={ratio}
-      className="relative w-full flex-1 overflow-hidden rounded-lg"
+      className={cn(
+        "relative overflow-hidden rounded-lg",
+        inHorizontalStack ? "min-w-0 flex-1 basis-0" : "w-full",
+      )}
     >
       {/* eslint-disable-next-line @next/next/no-img-element */}
       <img

package/src/react/components/stack.tsx

@@ -2,6 +2,14 @@
 
 import type { ReactNode } from "react";
 import { cn } from "@neynar/ui/utils";
+import {
+  countRenderableChildren,
+  horizontalChildrenAreAllButtons,
+} from "../../stack-horizontal-utils.js";
+import {
+  SnapStackDirectionProvider,
+  useSnapStackDirection,
+} from "../stack-direction-context";
 
 const VGAP: Record<string, string> = {
   none: "gap-0",
@@ -17,7 +25,7 @@ const HGAP: Record<string, string> = {
   lg: "gap-3",
 };
 
-const JUSTIFY: Record<string, string> = {
+const JUSTIFY_FLEX: Record<string, string> = {
   start: "justify-start",
   center: "justify-center",
   end: "justify-end",
@@ -25,6 +33,16 @@ const JUSTIFY: Record<string, string> = {
   around: "justify-around",
 };
 
+/** Equal columns for explicit `columns` prop and for all-button horizontal rows. */
+const COLUMN_GRID_CLASS: Record<number, string> = {
+  1: "grid grid-cols-1 auto-rows-auto items-stretch [&>*]:min-w-0",
+  2: "grid grid-cols-2 auto-rows-auto items-stretch [&>*]:min-w-0",
+  3: "grid grid-cols-3 auto-rows-auto items-stretch [&>*]:min-w-0",
+  4: "grid grid-cols-4 auto-rows-auto items-stretch [&>*]:min-w-0",
+  5: "grid grid-cols-5 auto-rows-auto items-stretch [&>*]:min-w-0",
+  6: "grid grid-cols-6 auto-rows-auto items-stretch [&>*]:min-w-0",
+};
+
 export function SnapStack({
   element: { props },
   children,
@@ -32,24 +50,79 @@ export function SnapStack({
   element: { props: Record<string, unknown> };
   children?: ReactNode;
 }) {
+  const parentDirection = useSnapStackDirection();
   const direction = String(props.direction ?? "vertical");
   const gapKey = String(props.gap ?? "md");
   const isHorizontal = direction === "horizontal";
   const gap = isHorizontal
     ? (HGAP[gapKey] ?? "gap-2")
     : (VGAP[gapKey] ?? "gap-4");
-  const justify = props.justify ? JUSTIFY[String(props.justify)] : undefined;
+  const justifyKey = props.justify ? String(props.justify) : undefined;
+  const justifyFlex = justifyKey ? JUSTIFY_FLEX[justifyKey] : undefined;
+  const buttonRowGrid =
+    isHorizontal && horizontalChildrenAreAllButtons(children);
+  const buttonRowCount = buttonRowGrid
+    ? countRenderableChildren(children)
+    : 0;
+
+  const columnsRaw = props.columns;
+  const columns =
+    typeof columnsRaw === "number" &&
+    columnsRaw >= 2 &&
+    columnsRaw <= 6 &&
+    Number.isInteger(columnsRaw)
+      ? columnsRaw
+      : undefined;
+  const explicitColumnGrid =
+    isHorizontal && columns !== undefined && !buttonRowGrid;
+  const columnGridClass =
+    explicitColumnGrid && columns !== undefined
+      ? COLUMN_GRID_CLASS[columns]
+      : undefined;
+
+  /**
+   * Row peers under a horizontal stack must shrink and share width (`flex-1` + `min-w-0`).
+   * Avoid `w-full` here: it resolves to 100% of the flex/grid container and fights peer sizing,
+   * so each column stacks on its own wrapped row instead of sitting side-by-side.
+   */
+  const isRowChild = parentDirection === "horizontal";
+  const rootWidthClass = isRowChild
+    ? "min-w-0 flex-1 basis-0 max-w-full"
+    : "w-full min-w-0";
+
+  const justifyBlockGrid =
+    justifyFlex &&
+    (!isHorizontal || (!buttonRowGrid && !explicitColumnGrid));
+
+  /** Single flex row (nowrap): peers stay side-by-side and shrink via min-w-0 / flex-1 on nested stacks. */
+  const horizontalFlexClasses =
+    "flex min-w-0 flex-row flex-nowrap items-stretch [&>*]:min-w-0";
 
   return (
-    <div
-      className={cn(
-        "flex w-full",
-        isHorizontal ? "flex-row items-center flex-wrap" : "flex-col",
-        gap,
-        justify,
-      )}
+    <SnapStackDirectionProvider
+      direction={isHorizontal ? "horizontal" : "vertical"}
     >
-      {children}
-    </div>
+      <div
+        className={cn(
+          rootWidthClass,
+          isHorizontal
+            ? buttonRowGrid &&
+                buttonRowCount >= 1 &&
+                buttonRowCount <= 6 &&
+                COLUMN_GRID_CLASS[buttonRowCount]
+              ? cn(
+                  COLUMN_GRID_CLASS[buttonRowCount]!,
+                  gap,
+                  "[&>*]:w-full",
+                )
+              : explicitColumnGrid && columnGridClass
+                ? cn(columnGridClass, gap)
+                : cn(horizontalFlexClasses, gap, justifyBlockGrid ? justifyFlex : undefined)
+            : cn("flex min-w-0 w-full flex-col", gap, justifyFlex),
+        )}
+      >
+        {children}
+      </div>
+    </SnapStackDirectionProvider>
   );
 }

package/src/react/components/text.tsx

@@ -1,7 +1,9 @@
 "use client";
 
 import { Text } from "@neynar/ui/typography";
+import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors";
+import { useSnapStackDirection } from "../stack-direction-context";
 
 const SIZE_MAP = {
   md: { textSize: "base" as const },
@@ -19,13 +21,18 @@ export function SnapText({
   const align = (props.align as "left" | "center" | "right") ?? undefined;
   const config = SIZE_MAP[size] ?? SIZE_MAP.md;
   const colors = useSnapColors();
+  const stackDir = useSnapStackDirection();
+  const inHorizontalStack = stackDir === "horizontal";
 
   return (
     <Text
       size={config.textSize}
       weight={weight}
       align={align}
-      className="flex-1"
+      className={cn(
+        /** Row peers hug content like RN `wrapRow`; avoid `flex-1` stretching peers across the row. */
+        inHorizontalStack ? "min-w-0 shrink" : "flex-1",
+      )}
       style={{ color: colors.text }}
     >
       {content}

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

@@ -4,8 +4,7 @@ import { useMemo } from "react";
 import { useStateStore } from "@json-render/react";
 import { resolveSnapPaletteHex } from "../lib/resolve-palette-hex";
 import { useSnapPreviewPageAccent, useSnapAppearance } from "../accent-context";
-import type { PaletteColor } from "@farcaster/snap";
-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: string): string {
@@ -76,7 +75,6 @@ function buildSnapColors(
   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"
@@ -87,11 +85,8 @@ function buildSnapColors(
 
   const paletteHex = (name: string) => resolveSnapPaletteHex(name, mode);
 
-  const colorHex = (name: string | undefined) => {
-    if (!name || name === "accent") return accent;
-    if (Object.hasOwn(paletteMap, name)) return paletteMap[name as PaletteColor];
-    return accent;
-  };
+  const colorHex = (name: string | undefined) =>
+    resolveSnapColorHex(name, { accentHex: accent, appearance: mode });
 
   return {
     accent,

package/src/react/stack-direction-context.tsx

@@ -0,0 +1,27 @@
+"use client";
+
+import { createContext, useContext, type ReactNode } from "react";
+
+export type SnapStackDirection = "vertical" | "horizontal";
+
+const SnapStackDirectionContext = createContext<SnapStackDirection | undefined>(
+  undefined,
+);
+
+export function SnapStackDirectionProvider({
+  direction,
+  children,
+}: {
+  direction: SnapStackDirection;
+  children: ReactNode;
+}) {
+  return (
+    <SnapStackDirectionContext.Provider value={direction}>
+      {children}
+    </SnapStackDirectionContext.Provider>
+  );
+}
+
+export function useSnapStackDirection(): SnapStackDirection | undefined {
+  return useContext(SnapStackDirectionContext);
+}

package/src/react-native/components/snap-cell-grid.tsx

@@ -66,13 +66,17 @@ export function SnapCellGrid({
   const ringOuter = appearance === "dark" ? "#fff" : "#000";
   const ringInner = appearance === "dark" ? "#000" : "#fff";
 
+  /** Cells without a palette `color` — subtle fill so empty slots read as tiles. */
+  const emptyCellBg =
+    appearance === "dark" ? "rgba(255, 255, 255, 0.05)" : "rgba(0, 0, 0, 0.05)";
+
   const rowEls = [];
   for (let r = 0; r < rows; r++) {
     const rowCells = [];
     for (let c = 0; c < cols; c++) {
       const cell = cellMap.get(`${r},${c}`);
       const selected = interactive && isSelected(r, c);
-      const bg = cell?.color ? hex(cell.color) : "transparent";
+      const bg = cell?.color ? hex(cell.color) : emptyCellBg;
 
       const cellContent = cell?.content ? (
         <Text style={[styles.cellText, { color: colors.textPrimary }]}>
@@ -121,18 +125,9 @@ export function SnapCellGrid({
     );
   }
 
-  const selectionLabel = isSelectable && selectedSet.size > 0
-    ? `inputs.${name}: ${[...selectedSet].join(isMultiple ? " | " : "")}`
-    : null;
-
   return (
     <View style={[styles.wrap, { gap: gapPx, backgroundColor: colors.muted, padding: 4, borderRadius: 8 }]}>
       {rowEls}
-      {selectionLabel ? (
-        <Text style={[styles.selectionText, { color: colors.textSecondary }]}>
-          {selectionLabel}
-        </Text>
-      ) : null}
     </View>
   );
 }
@@ -153,5 +148,4 @@ const styles = StyleSheet.create({
     justifyContent: "center",
   },
   cellText: { fontSize: 12, lineHeight: 16, fontWeight: "600" },
-  selectionText: { fontSize: 11, fontFamily: "monospace", marginTop: 6 },
 });

package/src/react-native/components/snap-image.tsx

@@ -1,6 +1,7 @@
 import type { ComponentRenderProps } from "@json-render/react-native";
 import { Image } from "expo-image";
 import { StyleSheet, View } from "react-native";
+import { useSnapStackDirection } from "../stack-direction-context";
 
 function aspectToRatio(aspect: string): number {
   const [w, h] = aspect.split(":").map(Number);
@@ -14,9 +15,17 @@ export function SnapImage({
   const url = String(props.url ?? "");
   const alt = String(props.alt ?? "");
   const ratio = aspectToRatio(String(props.aspect ?? "1:1"));
+  const stackDir = useSnapStackDirection();
+  const inHorizontalStack = stackDir === "horizontal";
 
   return (
-    <View style={[styles.frame, { aspectRatio: ratio }]}>
+    <View
+      style={[
+        styles.frame,
+        inHorizontalStack ? styles.frameInHorizontalRow : styles.frameFullWidth,
+        { aspectRatio: ratio },
+      ]}
+    >
       <Image
         source={{ uri: url }}
         style={StyleSheet.absoluteFill}
@@ -29,9 +38,15 @@ export function SnapImage({
 
 const styles = StyleSheet.create({
   frame: {
-    width: "100%",
     borderRadius: 8,
     overflow: "hidden",
     backgroundColor: "#f3f4f6",
   },
+  frameFullWidth: {
+    width: "100%",
+  },
+  frameInHorizontalRow: {
+    flex: 1,
+    minWidth: 0,
+  },
 });

package/src/react-native/components/snap-item.tsx

@@ -1,6 +1,7 @@
 import type { ComponentRenderProps } from "@json-render/react-native";
 import type { ReactNode } from "react";
 import { StyleSheet, Text, View } from "react-native";
+import { useSnapStackDirection } from "../stack-direction-context";
 import { useSnapTheme } from "../theme";
 
 export function SnapItem({
@@ -12,12 +13,19 @@ export function SnapItem({
   const description = props.description
     ? String(props.description)
     : undefined;
-  const variant = String(props.variant ?? "default");
+  /** Match web `Item className="flex-1"`: row peers must share width or title/description collapse. */
+  const rowPeer = useSnapStackDirection() === "horizontal";
 
   const containerVariant = { paddingVertical: 6, paddingHorizontal: 10 };
 
   return (
-    <View style={[styles.container, containerVariant]}>
+    <View
+      style={[
+        styles.container,
+        containerVariant,
+        rowPeer && styles.rowPeer,
+      ]}
+    >
       <View style={styles.content}>
         {title ? <Text style={[styles.title, { color: colors.text }]}>{title}</Text> : null}
         {description ? (
@@ -40,6 +48,10 @@ const styles = StyleSheet.create({
     flexDirection: "row",
     alignItems: "center",
   },
+  rowPeer: {
+    flex: 1,
+    minWidth: 0,
+  },
   content: {
     flex: 1,
   },

package/src/react-native/components/snap-progress.tsx

@@ -1,5 +1,6 @@
 import type { ComponentRenderProps } from "@json-render/react-native";
 import { StyleSheet, Text, View } from "react-native";
+import { useSnapStackDirection } from "../stack-direction-context";
 import { useSnapPalette } from "../use-snap-palette";
 import { useSnapTheme } from "../theme";
 
@@ -12,9 +13,10 @@ export function SnapProgress({
   const max = Math.max(1, Number(props.max ?? 100));
   const percent = Math.min(100, Math.max(0, (value / max) * 100));
   const label = props.label != null ? String(props.label) : null;
+  const inHorizontalStack = useSnapStackDirection() === "horizontal";
 
   return (
-    <View style={styles.wrap}>
+    <View style={[styles.wrap, inHorizontalStack ? styles.wrapRowPeer : styles.wrapCol]}>
       {label ? (
         <Text style={[styles.label, { color: colors.textSecondary }]}>{label}</Text>
       ) : null}
@@ -26,7 +28,11 @@ export function SnapProgress({
 }
 
 const styles = StyleSheet.create({
-  wrap: { width: "100%", gap: 4 },
+  wrap: { gap: 4 },
+  /** Vertical stacks: span card width (matches web `w-full`). */
+  wrapCol: { width: "100%" },
+  /** Horizontal row peers: share space; `width: 100%` each overflows the row. */
+  wrapRowPeer: { flex: 1, minWidth: 0 },
   label: { fontSize: 13, lineHeight: 18 },
   track: {
     height: 10,