@farcaster/snap 2.2.0 → 2.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neynar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/dist/colors.d.ts

@@ -34,6 +34,14 @@ export declare function resolveSnapColorHex(color: string | undefined, opts: {
     accentHex: string;
     appearance: "light" | "dark";
 }): string;
+/**
+ * Pick a readable text color for a given hex background.
+ *
+ * Uses WCAG relative luminance with a 0.5 threshold. Returns `rgba(...)` so
+ * callers can soften the text against the background — defaults to 0.8 alpha
+ * to let a hint of the cell color bleed through.
+ */
+export declare function readableTextOnHex(hex: string, alpha?: number): 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

@@ -54,6 +54,27 @@ export function resolveSnapColorHex(color, opts) {
     }
     return opts.accentHex;
 }
+/**
+ * Pick a readable text color for a given hex background.
+ *
+ * Uses WCAG relative luminance with a 0.5 threshold. Returns `rgba(...)` so
+ * callers can soften the text against the background — defaults to 0.8 alpha
+ * to let a hint of the cell color bleed through.
+ */
+export function readableTextOnHex(hex, alpha = 0.8) {
+    const m = /^#([0-9a-fA-F]{6})$/.exec(hex.trim());
+    if (!m)
+        return `rgba(0,0,0,${alpha})`;
+    const n = Number.parseInt(m[1], 16);
+    const toLin = (c) => {
+        const s = c / 255;
+        return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+    };
+    const L = 0.2126 * toLin((n >> 16) & 0xff) +
+        0.7152 * toLin((n >> 8) & 0xff) +
+        0.0722 * toLin(n & 0xff);
+    return L >= 0.5 ? `rgba(0,0,0,${alpha})` : `rgba(255,255,255,${alpha})`;
+}
 /** Light-mode hex for each palette color (emulator / reference client). */
 export const PALETTE_LIGHT_HEX = {
     gray: "#6E6A86",

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, 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 { DEFAULT_THEME_ACCENT, PALETTE_COLOR, PALETTE_COLOR_ACCENT, PALETTE_COLOR_VALUES, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, isSnapHexColorString, readableTextOnHex, 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, 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 { DEFAULT_THEME_ACCENT, PALETTE_COLOR, PALETTE_COLOR_ACCENT, PALETTE_COLOR_VALUES, PALETTE_LIGHT_HEX, PALETTE_DARK_HEX, isSnapHexColorString, readableTextOnHex, 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/components/action-button.js

@@ -5,6 +5,7 @@ import { ExternalLink } from "lucide-react";
 import { Button } from "@neynar/ui/button";
 import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors.js";
+import { useSnapStackDirection } from "../stack-direction-context.js";
 import { ICON_MAP } from "./icon.js";
 function isExternalLinkAction(on) {
     if (!on)
@@ -24,6 +25,7 @@ export function SnapActionButton({ element, emit, }) {
     const [hovered, setHovered] = useState(false);
     const Icon = iconName ? ICON_MAP[iconName] : undefined;
     const showExternalIcon = isExternalLinkAction(element.on);
+    const inHorizontalStack = useSnapStackDirection() === "horizontal";
     const style = {
         cursor: "pointer",
         ...(isPrimary
@@ -40,5 +42,13 @@ export function SnapActionButton({ element, emit, }) {
                 borderColor: "transparent",
             }),
     };
-    return (_jsx("div", { className: "w-full min-w-0 flex-1", children: _jsxs(Button, { type: "button", variant: isPrimary ? "default" : "secondary", className: cn("w-full gap-2"), style: style, onClick: () => emit("press"), onPointerEnter: () => setHovered(true), onPointerLeave: () => setHovered(false), children: [Icon && _jsx(Icon, { size: 16 }), label, showExternalIcon && (_jsx(ExternalLink, { size: 14, style: { opacity: 0.6 } }))] }) }));
+    return (
+    /**
+     * In a horizontal stack, `flex-1` lets the wrapper share row width with peers.
+     * In a vertical stack, `flex-1` would silently grow the button to fill column
+     * height (1/N distribution when siblings also flex-grow); stick to `w-full`.
+     */
+    _jsx("div", { className: inHorizontalStack
+            ? "w-full min-w-0 flex-1"
+            : "w-full min-w-0", children: _jsxs(Button, { type: "button", variant: isPrimary ? "default" : "secondary", className: cn("w-full gap-2"), style: style, onClick: () => emit("press"), onPointerEnter: () => setHovered(true), onPointerLeave: () => setHovered(false), children: [Icon && _jsx(Icon, { size: 16 }), label, showExternalIcon && (_jsx(ExternalLink, { size: 14, style: { opacity: 0.6 } }))] }) }));
 }

package/dist/react/components/cell-grid.js

@@ -2,7 +2,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useStateStore } from "@json-render/react";
 import { cn } from "@neynar/ui/utils";
-import { POST_GRID_TAP_KEY } from "@farcaster/snap";
+import { POST_GRID_TAP_KEY, readableTextOnHex } from "@farcaster/snap";
 import { useSnapColors } from "../hooks/use-snap-colors.js";
 export function SnapCellGrid({ element: { props, on }, emit, }) {
     const { get, set } = useStateStore();
@@ -22,38 +22,46 @@ export function SnapCellGrid({ element: { props, on }, emit, }) {
     const name = props.name ? String(props.name) : POST_GRID_TAP_KEY;
     const tapPath = `/inputs/${name}`;
     const tapRaw = get(tapPath);
-    // Parse selection — single mode: "row,col" string; multi mode: "row,col|row,col|..." string
+    const cellMap = new Map();
+    for (const c of cells) {
+        cellMap.set(`${Number(c.row)},${Number(c.col)}`, {
+            color: c.color,
+            content: c.content != null ? String(c.content) : undefined,
+            value: typeof c.value === "string" ? c.value : undefined,
+        });
+    }
+    // Each cell's wire value — its `value` if set, otherwise "row,col" fallback.
+    const cellWireValue = (r, c) => cellMap.get(`${r},${c}`)?.value ?? `${r},${c}`;
+    // Multi mode joins values with `|`; single mode is the value itself.
     const selectedSet = new Set();
     if (typeof tapRaw === "string" && tapRaw.length > 0) {
-        for (const part of tapRaw.split("|")) {
-            if (part.includes(","))
-                selectedSet.add(part);
+        if (isMultiple) {
+            for (const part of tapRaw.split("|")) {
+                if (part.length > 0)
+                    selectedSet.add(part);
+            }
+        }
+        else {
+            selectedSet.add(tapRaw);
         }
     }
-    const isSelected = (r, c) => isSelectable && selectedSet.has(`${r},${c}`);
+    const isSelected = (r, c) => isSelectable && selectedSet.has(cellWireValue(r, c));
     const handleTap = (r, c) => {
-        const key = `${r},${c}`;
+        const wire = cellWireValue(r, c);
         if (isMultiple) {
             const next = new Set(selectedSet);
-            if (next.has(key))
-                next.delete(key);
+            if (next.has(wire))
+                next.delete(wire);
             else
-                next.add(key);
+                next.add(wire);
             set(tapPath, [...next].join("|"));
         }
         else {
-            set(tapPath, key);
+            set(tapPath, wire);
         }
         if (hasPressAction)
             emit("press");
     };
-    const cellMap = new Map();
-    for (const c of cells) {
-        cellMap.set(`${Number(c.row)},${Number(c.col)}`, {
-            color: c.color,
-            content: c.content != null ? String(c.content) : undefined,
-        });
-    }
     /** 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 = [];
@@ -61,7 +69,9 @@ export function SnapCellGrid({ element: { props, on }, emit, }) {
         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) : emptyCellBg;
+            const bgHex = cell?.color ? colors.colorHex(cell.color) : null;
+            const bg = bgHex ?? emptyCellBg;
+            const textColor = bgHex ? readableTextOnHex(bgHex) : colors.text;
             cellEls.push(_jsx("div", { role: interactive ? "button" : undefined, tabIndex: interactive ? 0 : undefined, onClick: interactive ? () => handleTap(r, c) : undefined, onKeyDown: interactive
                     ? (e) => {
                         if (e.key === "Enter" || e.key === " ") {
@@ -72,6 +82,7 @@ export function SnapCellGrid({ element: { props, on }, emit, }) {
                     : undefined, className: cn("flex items-center justify-center rounded text-xs font-semibold", interactive ? "cursor-pointer select-none" : "cursor-default"), style: {
                     height: rowHeight,
                     background: bg,
+                    color: textColor,
                     boxShadow: selected
                         ? `inset 0 0 0 1px ${colors.mode === "dark" ? "#000" : "#fff"}, inset 0 0 0 2px ${colors.mode === "dark" ? "#fff" : "#000"}`
                         : undefined,

package/dist/react/components/item.js

@@ -1,10 +1,15 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Item, ItemContent, ItemTitle, ItemDescription, ItemActions, } from "@neynar/ui/item";
+import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors.js";
+import { useSnapStackDirection } from "../stack-direction-context.js";
 export function SnapItem({ element: { props, children: childIds }, children, }) {
     const title = String(props.title ?? "");
     const description = props.description ? String(props.description) : undefined;
     const colors = useSnapColors();
-    return (_jsxs(Item, { className: "flex-1 py-1.5 px-2.5", children: [_jsxs(ItemContent, { className: "gap-0.5", children: [_jsx(ItemTitle, { style: { color: colors.text }, children: title }), description && (_jsx(ItemDescription, { className: "mt-0", style: { color: colors.textMuted }, children: description }))] }), childIds && childIds.length > 0 && _jsx(ItemActions, { children: children })] }));
+    const inHorizontalStack = useSnapStackDirection() === "horizontal";
+    return (_jsxs(Item, { className: cn("py-1.5 px-2.5", 
+        /** Horizontal: share width with peers. Vertical: don't fill column height. */
+        inHorizontalStack && "flex-1"), children: [_jsxs(ItemContent, { className: "gap-0.5", children: [_jsx(ItemTitle, { style: { color: colors.text }, children: title }), description && (_jsx(ItemDescription, { className: "mt-0", style: { color: colors.textMuted }, children: description }))] }), childIds && childIds.length > 0 && _jsx(ItemActions, { children: children })] }));
 }

package/dist/react/components/progress.js

@@ -1,11 +1,16 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors.js";
+import { useSnapStackDirection } from "../stack-direction-context.js";
 export function SnapProgress({ element: { props }, }) {
     const colors = useSnapColors();
     const value = Number(props.value ?? 0);
     const max = Math.max(1, Number(props.max ?? 100));
     const percent = Math.min(100, Math.max(0, (value / max) * 100));
     const label = props.label ? String(props.label) : null;
-    return (_jsxs("div", { className: "flex w-full flex-1 flex-col gap-1", children: [label && (_jsx("span", { className: "text-xs", style: { color: colors.textMuted }, children: label })), _jsx("div", { className: "h-2.5 w-full overflow-hidden rounded-full", style: { backgroundColor: colors.muted }, children: _jsx("div", { className: "h-full rounded-full transition-all", style: { width: `${percent}%`, backgroundColor: colors.accent } }) })] }));
+    const inHorizontalStack = useSnapStackDirection() === "horizontal";
+    return (_jsxs("div", { className: cn("flex w-full flex-col gap-1", 
+        /** Horizontal: share width with peers. Vertical: don't fill column height. */
+        inHorizontalStack && "flex-1"), children: [label && (_jsx("span", { className: "text-xs", style: { color: colors.textMuted }, children: label })), _jsx("div", { className: "h-2.5 w-full overflow-hidden rounded-full", style: { backgroundColor: colors.muted }, children: _jsx("div", { className: "h-full rounded-full transition-all", style: { width: `${percent}%`, backgroundColor: colors.accent } }) })] }));
 }

package/dist/react/components/stack.js

@@ -1,7 +1,7 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cn } from "@neynar/ui/utils";
-import { countRenderableChildren, horizontalChildrenAreAllButtons, } from "../../stack-horizontal-utils.js";
+import { countRenderableChildren, defaultHorizontalGapSize, horizontalChildrenAreAllButtons, } from "../../stack-horizontal-utils.js";
 import { SnapStackDirectionProvider, useSnapStackDirection, } from "../stack-direction-context.js";
 const VGAP = {
     none: "gap-0",
@@ -13,7 +13,7 @@ const HGAP = {
     none: "gap-0",
     sm: "gap-1",
     md: "gap-2",
-    lg: "gap-3",
+    lg: "gap-4",
 };
 const JUSTIFY_FLEX = {
     start: "justify-start",
@@ -34,11 +34,7 @@ const COLUMN_GRID_CLASS = {
 export function SnapStack({ element: { props }, children, }) {
     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 justifyKey = props.justify ? String(props.justify) : undefined;
     const justifyFlex = justifyKey ? JUSTIFY_FLEX[justifyKey] : undefined;
     const buttonRowGrid = isHorizontal && horizontalChildrenAreAllButtons(children);
@@ -52,6 +48,23 @@ export function SnapStack({ element: { props }, children, }) {
         Number.isInteger(columnsRaw)
         ? columnsRaw
         : undefined;
+    // Horizontal default depends on column count: 2→lg, 3→md, 4+→sm. Vertical stays md.
+    // Count comes from explicit `columns`, then button-row inference, else direct children
+    // count (any horizontal stack is N columns wide regardless of child types).
+    const horizontalColumnCount = isHorizontal
+        ? (columns ??
+            (buttonRowGrid ? buttonRowCount : undefined) ??
+            countRenderableChildren(children))
+        : undefined;
+    const explicitGap = typeof props.gap === "string" && props.gap in (isHorizontal ? HGAP : VGAP);
+    const gapKey = explicitGap
+        ? String(props.gap)
+        : isHorizontal
+            ? defaultHorizontalGapSize(horizontalColumnCount)
+            : "md";
+    const gap = isHorizontal
+        ? (HGAP[gapKey] ?? HGAP.md)
+        : (VGAP[gapKey] ?? VGAP.md);
     const explicitColumnGrid = isHorizontal && columns !== undefined && !buttonRowGrid;
     const columnGridClass = explicitColumnGrid && columns !== undefined
         ? COLUMN_GRID_CLASS[columns]

package/dist/react/components/text.js

@@ -18,6 +18,13 @@ export function SnapText({ element: { props }, }) {
     const stackDir = useSnapStackDirection();
     const inHorizontalStack = stackDir === "horizontal";
     return (_jsx(Text, { size: config.textSize, weight: weight, align: align, 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 }, children: content }));
+        /**
+         * Row peers hug content like RN `wrapRow` — `min-w-0 shrink` lets text wrap
+         * inside a horizontal stack without forcing peers wide. In a vertical stack
+         * the `<p>` already fills its parent's width via `display: block`; avoid
+         * `flex-1` here because `flex-grow: 1` on a vertical-flex child fills the
+         * column's height, distributing siblings when the row is taller than its
+         * content (e.g. text next to a tall image).
+         */
+        inHorizontalStack ? "min-w-0 shrink" : "min-w-0"), style: { color: colors.text }, children: content }));
 }

package/dist/react-native/components/snap-cell-grid.js

@@ -3,7 +3,7 @@ import { StyleSheet, Text, View, Pressable } from "react-native";
 import { useStateStore } from "@json-render/react-native";
 import { useSnapPalette } from "../use-snap-palette.js";
 import { useSnapTheme } from "../theme.js";
-import { POST_GRID_TAP_KEY } from "@farcaster/snap";
+import { POST_GRID_TAP_KEY, readableTextOnHex } from "@farcaster/snap";
 export function SnapCellGrid({ element, emit, }) {
     const { props } = element;
     const on = element.on;
@@ -25,37 +25,46 @@ export function SnapCellGrid({ element, emit, }) {
     const name = props.name ? String(props.name) : POST_GRID_TAP_KEY;
     const tapPath = `/inputs/${name}`;
     const tapRaw = get(tapPath);
+    const cellMap = new Map();
+    for (const c of cells) {
+        cellMap.set(`${Number(c.row)},${Number(c.col)}`, {
+            color: c.color,
+            content: c.content != null ? String(c.content) : undefined,
+            value: typeof c.value === "string" ? c.value : undefined,
+        });
+    }
+    // Each cell's wire value — its `value` if set, otherwise "row,col" fallback.
+    const cellWireValue = (r, c) => cellMap.get(`${r},${c}`)?.value ?? `${r},${c}`;
+    // Multi mode joins values with `|`; single mode is the value itself.
     const selectedSet = new Set();
     if (typeof tapRaw === "string" && tapRaw.length > 0) {
-        for (const part of tapRaw.split("|")) {
-            if (part.includes(","))
-                selectedSet.add(part);
+        if (isMultiple) {
+            for (const part of tapRaw.split("|")) {
+                if (part.length > 0)
+                    selectedSet.add(part);
+            }
+        }
+        else {
+            selectedSet.add(tapRaw);
         }
     }
-    const isSelected = (r, c) => isSelectable && selectedSet.has(`${r},${c}`);
+    const isSelected = (r, c) => isSelectable && selectedSet.has(cellWireValue(r, c));
     const handleTap = (r, c) => {
-        const key = `${r},${c}`;
+        const wire = cellWireValue(r, c);
         if (isMultiple) {
             const next = new Set(selectedSet);
-            if (next.has(key))
-                next.delete(key);
+            if (next.has(wire))
+                next.delete(wire);
             else
-                next.add(key);
+                next.add(wire);
             set(tapPath, [...next].join("|"));
         }
         else {
-            set(tapPath, key);
+            set(tapPath, wire);
         }
         if (hasPressAction)
             emit("press");
     };
-    const cellMap = new Map();
-    for (const c of cells) {
-        cellMap.set(`${Number(c.row)},${Number(c.col)}`, {
-            color: c.color,
-            content: c.content != null ? String(c.content) : undefined,
-        });
-    }
     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. */
@@ -66,8 +75,10 @@ export function SnapCellGrid({ element, emit, }) {
         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) : emptyCellBg;
-            const cellContent = cell?.content ? (_jsx(Text, { style: [styles.cellText, { color: colors.textPrimary }], children: cell.content })) : null;
+            const bgHex = cell?.color ? hex(cell.color) : null;
+            const bg = bgHex ?? emptyCellBg;
+            const textColor = bgHex ? readableTextOnHex(bgHex) : colors.text;
+            const cellContent = cell?.content ? (_jsx(Text, { style: [styles.cellText, { color: textColor }], children: cell.content })) : null;
             // Two-tone ring: outer View with contrasting border, inner View with inverse border
             const cellView = selected ? (_jsx(View, { style: [styles.cell, { height: rowHeight, borderWidth: 1, borderColor: ringOuter, borderRadius: 4 }], children: _jsx(View, { style: [
                         styles.innerCell,

package/dist/react-native/components/snap-stack.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Children } from "react";
 import { StyleSheet, View } from "react-native";
-import { countRenderableChildren, horizontalChildrenAreAllButtons, } from "../../stack-horizontal-utils.js";
+import { countRenderableChildren, defaultHorizontalGapSize, horizontalChildrenAreAllButtons, } from "../../stack-horizontal-utils.js";
 import { SnapStackDirectionProvider, useSnapStackDirection, } from "../stack-direction-context.js";
 const VGAP = {
     none: 0,
@@ -13,7 +13,7 @@ const HGAP = {
     none: 0,
     sm: 4,
     md: 8,
-    lg: 12,
+    lg: 16,
 };
 const JUSTIFY = {
     start: "flex-start",
@@ -33,11 +33,6 @@ export function SnapStack({ element: { props }, children, }) {
     const rawGap = props.gap;
     const isHorizontal = direction === "horizontal";
     const gapMap = isHorizontal ? HGAP : VGAP;
-    const gap = typeof rawGap === "number"
-        ? rawGap
-        : typeof rawGap === "string" && rawGap in gapMap
-            ? gapMap[rawGap]
-            : isHorizontal ? HGAP.md : VGAP.md;
     const buttonRowGrid = isHorizontal && horizontalChildrenAreAllButtons(children);
     const buttonRowCount = buttonRowGrid
         ? countRenderableChildren(children)
@@ -49,6 +44,21 @@ export function SnapStack({ element: { props }, children, }) {
         Number.isInteger(columnsRaw)
         ? columnsRaw
         : undefined;
+    // Horizontal default depends on column count: 2→lg, 3→md, 4+→sm. Vertical stays md.
+    // Count comes from explicit `columns`, then button-row inference, else direct children
+    // count (any horizontal stack is N columns wide regardless of child types).
+    const horizontalColumnCount = isHorizontal
+        ? (columns ??
+            (buttonRowGrid ? buttonRowCount : undefined) ??
+            countRenderableChildren(children))
+        : undefined;
+    const gap = typeof rawGap === "number"
+        ? rawGap
+        : typeof rawGap === "string" && rawGap in gapMap
+            ? gapMap[rawGap]
+            : isHorizontal
+                ? gapMap[defaultHorizontalGapSize(horizontalColumnCount)]
+                : VGAP.md;
     const explicitColumnGrid = isHorizontal && columns !== undefined && !buttonRowGrid;
     const justify = props.justify &&
         (!isHorizontal || (!buttonRowGrid && !explicitColumnGrid))

package/dist/stack-horizontal-utils.d.ts

@@ -2,3 +2,9 @@ import { type ReactNode } from "react";
 export declare function horizontalChildrenAreAllButtons(children: ReactNode): boolean;
 /** Direct snap catalog children under a stack (used for all-button grid column count). */
 export declare function countRenderableChildren(children: ReactNode): number;
+/**
+ * Default horizontal stack gap as a t-shirt size, chosen by column count:
+ * 2 cols → lg, 3 cols → md, 4+ cols → sm. Unknown count falls back to md.
+ * Tighter gaps for denser layouts; authors can always override via the `gap` prop.
+ */
+export declare function defaultHorizontalGapSize(columnCount: number | undefined): "sm" | "md" | "lg";

package/dist/stack-horizontal-utils.js

@@ -27,3 +27,17 @@ export function horizontalChildrenAreAllButtons(children) {
 export function countRenderableChildren(children) {
     return Children.toArray(children).filter(isRenderableChild).length;
 }
+/**
+ * Default horizontal stack gap as a t-shirt size, chosen by column count:
+ * 2 cols → lg, 3 cols → md, 4+ cols → sm. Unknown count falls back to md.
+ * Tighter gaps for denser layouts; authors can always override via the `gap` prop.
+ */
+export function defaultHorizontalGapSize(columnCount) {
+    if (columnCount === undefined)
+        return "md";
+    if (columnCount <= 2)
+        return "lg";
+    if (columnCount === 3)
+        return "md";
+    return "sm";
+}

package/dist/ui/catalog.d.ts

@@ -391,6 +391,7 @@ export declare const snapJsonRenderCatalog: import("@json-render/core").Catalog<
                         pink: "pink";
                     }>, z.ZodString]>>>;
                     content: z.ZodOptional<z.ZodString>;
+                    value: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>>;
                 gap: z.ZodOptional<z.ZodEnum<{
                     sm: "sm";

package/dist/ui/cell-grid.d.ts

@@ -17,6 +17,7 @@ export declare const cellGridProps: z.ZodObject<{
             pink: "pink";
         }>, z.ZodString]>>>;
         content: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     gap: z.ZodOptional<z.ZodEnum<{
         sm: "sm";

package/dist/ui/cell-grid.js

@@ -15,6 +15,7 @@ const cellGridCellSchema = z.object({
     col: z.number().int().nonnegative(),
     color: cellGridCellColorSchema.optional(),
     content: z.string().optional(),
+    value: z.string().min(1).max(30).optional(),
 });
 export const cellGridProps = z
     .object({

package/llms.txt

@@ -95,17 +95,17 @@ 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 | #rrggbb, content?: string }`
+- `cells` (array, required): sparse list of `{ row, col, color?: PaletteColor | #rrggbb, content?: string, value?: string (1–30 chars) }`. When `value` is set on a cell, that string is what's written to `inputs[name]` on press/select; otherwise `"row,col"` is used. Use `value` for grids with meaningful labels (calendar days, alphabet letters, region codes) so handlers don't have to reverse-lookup. Use the row/col fallback for true coordinate grids (minesweeper, tic-tac-toe, pixel art).
 - `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.
-- Events: `press` — fires on cell press, only when `select: "off"`; `inputs[name]` is set to `"row,col"` before the bound action runs
+- `select` (optional): `"off"` | `"single"` | `"multiple"`. Default: `"off"`. With `select: "off"`, bind `on.press` for press-to-act (each press writes the cell's `value` or `"row,col"` to `inputs[name]` and fires the action). With `"single"` / `"multiple"`, presses accumulate selection state and pair with a separate submit `button` (multi-select joins values with `|`); `on.press` is ignored.
+- Events: `press` — fires on cell press, only when `select: "off"`; `inputs[name]` is set to the pressed cell's `value` (or `"row,col"` fallback) before the bound action runs
 
 ### Container Components
 
 **stack** — Layout container.
 - `direction` (optional): `"vertical"` | `"horizontal"`. Default: `"vertical"`
-- `gap` (optional): `"none"` | `"sm"` | `"md"` | `"lg"`. Default: `"md"`
+- `gap` (optional): `"none"` | `"sm"` | `"md"` | `"lg"`. Vertical px: 0/8/16/24. Horizontal px: 0/4/8/16 (tighter, since children sit side-by-side). Default for vertical: `"md"`. Default for horizontal is column-aware: 2 cols → `"lg"` (16px), 3 cols → `"md"` (8px), 4+ cols → `"sm"` (4px), unknown → `"md"` (8px). An explicit value always wins — override the default when you have a deliberate visual reason (e.g. tighter toolbar, extra breathing room around a hero row).
 - `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

package/package.json

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

package/src/colors.ts

@@ -65,6 +65,28 @@ export function resolveSnapColorHex(
   return opts.accentHex;
 }
 
+/**
+ * Pick a readable text color for a given hex background.
+ *
+ * Uses WCAG relative luminance with a 0.5 threshold. Returns `rgba(...)` so
+ * callers can soften the text against the background — defaults to 0.8 alpha
+ * to let a hint of the cell color bleed through.
+ */
+export function readableTextOnHex(hex: string, alpha = 0.8): string {
+  const m = /^#([0-9a-fA-F]{6})$/.exec(hex.trim());
+  if (!m) return `rgba(0,0,0,${alpha})`;
+  const n = Number.parseInt(m[1], 16);
+  const toLin = (c: number) => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  const L =
+    0.2126 * toLin((n >> 16) & 0xff) +
+    0.7152 * toLin((n >> 8) & 0xff) +
+    0.0722 * toLin(n & 0xff);
+  return L >= 0.5 ? `rgba(0,0,0,${alpha})` : `rgba(255,255,255,${alpha})`;
+}
+
 /** Light-mode hex for each palette color (emulator / reference client). */
 export const PALETTE_LIGHT_HEX: Record<PaletteColor, string> = {
   gray: "#6E6A86",

package/src/index.ts

@@ -25,6 +25,7 @@ export {
   PALETTE_LIGHT_HEX,
   PALETTE_DARK_HEX,
   isSnapHexColorString,
+  readableTextOnHex,
   resolveSnapColorHex,
   type PaletteColor,
 } from "./colors";

package/src/react/components/action-button.tsx

@@ -5,6 +5,7 @@ import { ExternalLink } from "lucide-react";
 import { Button } from "@neynar/ui/button";
 import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors";
+import { useSnapStackDirection } from "../stack-direction-context";
 import { ICON_MAP } from "./icon";
 
 function isExternalLinkAction(
@@ -38,6 +39,7 @@ export function SnapActionButton({
 
   const Icon = iconName ? ICON_MAP[iconName] : undefined;
   const showExternalIcon = isExternalLinkAction(element.on);
+  const inHorizontalStack = useSnapStackDirection() === "horizontal";
 
   const style = {
     cursor: "pointer" as const,
@@ -57,7 +59,18 @@ export function SnapActionButton({
   };
 
   return (
-    <div className="w-full min-w-0 flex-1">
+    /**
+     * In a horizontal stack, `flex-1` lets the wrapper share row width with peers.
+     * In a vertical stack, `flex-1` would silently grow the button to fill column
+     * height (1/N distribution when siblings also flex-grow); stick to `w-full`.
+     */
+    <div
+      className={
+        inHorizontalStack
+          ? "w-full min-w-0 flex-1"
+          : "w-full min-w-0"
+      }
+    >
       <Button
         type="button"
         variant={isPrimary ? "default" : "secondary"}

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

@@ -3,7 +3,7 @@
 import type { ReactNode } from "react";
 import { useStateStore } from "@json-render/react";
 import { cn } from "@neynar/ui/utils";
-import { POST_GRID_TAP_KEY } from "@farcaster/snap";
+import { POST_GRID_TAP_KEY, readableTextOnHex } from "@farcaster/snap";
 import { useSnapColors } from "../hooks/use-snap-colors";
 
 export function SnapCellGrid({
@@ -32,38 +32,50 @@ export function SnapCellGrid({
   const tapPath = `/inputs/${name}`;
   const tapRaw = get(tapPath);
 
-  // Parse selection — single mode: "row,col" string; multi mode: "row,col|row,col|..." string
+  const cellMap = new Map<
+    string,
+    { color?: string; content?: string; value?: string }
+  >();
+  for (const c of cells) {
+    cellMap.set(`${Number(c.row)},${Number(c.col)}`, {
+      color: c.color as string | undefined,
+      content: c.content != null ? String(c.content) : undefined,
+      value: typeof c.value === "string" ? c.value : undefined,
+    });
+  }
+
+  // Each cell's wire value — its `value` if set, otherwise "row,col" fallback.
+  const cellWireValue = (r: number, c: number) =>
+    cellMap.get(`${r},${c}`)?.value ?? `${r},${c}`;
+
+  // Multi mode joins values with `|`; single mode is the value itself.
   const selectedSet = new Set<string>();
   if (typeof tapRaw === "string" && tapRaw.length > 0) {
-    for (const part of tapRaw.split("|")) {
-      if (part.includes(",")) selectedSet.add(part);
+    if (isMultiple) {
+      for (const part of tapRaw.split("|")) {
+        if (part.length > 0) selectedSet.add(part);
+      }
+    } else {
+      selectedSet.add(tapRaw);
     }
   }
 
   const isSelected = (r: number, c: number) =>
-    isSelectable && selectedSet.has(`${r},${c}`);
+    isSelectable && selectedSet.has(cellWireValue(r, c));
 
   const handleTap = (r: number, c: number) => {
-    const key = `${r},${c}`;
+    const wire = cellWireValue(r, c);
     if (isMultiple) {
       const next = new Set(selectedSet);
-      if (next.has(key)) next.delete(key);
-      else next.add(key);
+      if (next.has(wire)) next.delete(wire);
+      else next.add(wire);
       set(tapPath, [...next].join("|"));
     } else {
-      set(tapPath, key);
+      set(tapPath, wire);
     }
     if (hasPressAction) emit("press");
   };
 
-  const cellMap = new Map<string, { color?: string; content?: string }>();
-  for (const c of cells) {
-    cellMap.set(`${Number(c.row)},${Number(c.col)}`, {
-      color: c.color as string | undefined,
-      content: c.content != null ? String(c.content) : undefined,
-    });
-  }
-
   /** 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)";
@@ -73,7 +85,9 @@ export function SnapCellGrid({
     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) : emptyCellBg;
+      const bgHex = cell?.color ? colors.colorHex(cell.color) : null;
+      const bg = bgHex ?? emptyCellBg;
+      const textColor = bgHex ? readableTextOnHex(bgHex) : colors.text;
 
       cellEls.push(
         <div
@@ -98,6 +112,7 @@ export function SnapCellGrid({
           style={{
             height: rowHeight,
             background: bg,
+            color: textColor,
             boxShadow: selected
               ? `inset 0 0 0 1px ${colors.mode === "dark" ? "#000" : "#fff"}, inset 0 0 0 2px ${colors.mode === "dark" ? "#fff" : "#000"}`
               : undefined,

package/src/react/components/item.tsx

@@ -7,7 +7,9 @@ import {
   ItemDescription,
   ItemActions,
 } from "@neynar/ui/item";
+import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors";
+import { useSnapStackDirection } from "../stack-direction-context";
 
 export function SnapItem({
   element: { props, children: childIds },
@@ -19,9 +21,16 @@ export function SnapItem({
   const title = String(props.title ?? "");
   const description = props.description ? String(props.description) : undefined;
   const colors = useSnapColors();
+  const inHorizontalStack = useSnapStackDirection() === "horizontal";
 
   return (
-    <Item className="flex-1 py-1.5 px-2.5">
+    <Item
+      className={cn(
+        "py-1.5 px-2.5",
+        /** Horizontal: share width with peers. Vertical: don't fill column height. */
+        inHorizontalStack && "flex-1",
+      )}
+    >
       <ItemContent className="gap-0.5">
         <ItemTitle style={{ color: colors.text }}>{title}</ItemTitle>
         {description && (

package/src/react/components/progress.tsx

@@ -1,6 +1,8 @@
 "use client";
 
+import { cn } from "@neynar/ui/utils";
 import { useSnapColors } from "../hooks/use-snap-colors";
+import { useSnapStackDirection } from "../stack-direction-context";
 
 export function SnapProgress({
   element: { props },
@@ -12,9 +14,16 @@ 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 ? String(props.label) : null;
+  const inHorizontalStack = useSnapStackDirection() === "horizontal";
 
   return (
-    <div className="flex w-full flex-1 flex-col gap-1">
+    <div
+      className={cn(
+        "flex w-full flex-col gap-1",
+        /** Horizontal: share width with peers. Vertical: don't fill column height. */
+        inHorizontalStack && "flex-1",
+      )}
+    >
       {label && (
         <span className="text-xs" style={{ color: colors.textMuted }}>
           {label}

package/src/react/components/stack.tsx

@@ -4,6 +4,7 @@ import type { ReactNode } from "react";
 import { cn } from "@neynar/ui/utils";
 import {
   countRenderableChildren,
+  defaultHorizontalGapSize,
   horizontalChildrenAreAllButtons,
 } from "../../stack-horizontal-utils.js";
 import {
@@ -22,7 +23,7 @@ const HGAP: Record<string, string> = {
   none: "gap-0",
   sm: "gap-1",
   md: "gap-2",
-  lg: "gap-3",
+  lg: "gap-4",
 };
 
 const JUSTIFY_FLEX: Record<string, string> = {
@@ -52,11 +53,7 @@ export function SnapStack({
 }) {
   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 justifyKey = props.justify ? String(props.justify) : undefined;
   const justifyFlex = justifyKey ? JUSTIFY_FLEX[justifyKey] : undefined;
   const buttonRowGrid =
@@ -73,6 +70,25 @@ export function SnapStack({
     Number.isInteger(columnsRaw)
       ? columnsRaw
       : undefined;
+
+  // Horizontal default depends on column count: 2→lg, 3→md, 4+→sm. Vertical stays md.
+  // Count comes from explicit `columns`, then button-row inference, else direct children
+  // count (any horizontal stack is N columns wide regardless of child types).
+  const horizontalColumnCount = isHorizontal
+    ? (columns ??
+       (buttonRowGrid ? buttonRowCount : undefined) ??
+       countRenderableChildren(children))
+    : undefined;
+  const explicitGap =
+    typeof props.gap === "string" && props.gap in (isHorizontal ? HGAP : VGAP);
+  const gapKey = explicitGap
+    ? String(props.gap)
+    : isHorizontal
+      ? defaultHorizontalGapSize(horizontalColumnCount)
+      : "md";
+  const gap = isHorizontal
+    ? (HGAP[gapKey] ?? HGAP.md!)
+    : (VGAP[gapKey] ?? VGAP.md!);
   const explicitColumnGrid =
     isHorizontal && columns !== undefined && !buttonRowGrid;
   const columnGridClass =

package/src/react/components/text.tsx

@@ -30,8 +30,15 @@ export function SnapText({
       weight={weight}
       align={align}
       className={cn(
-        /** Row peers hug content like RN `wrapRow`; avoid `flex-1` stretching peers across the row. */
-        inHorizontalStack ? "min-w-0 shrink" : "flex-1",
+        /**
+         * Row peers hug content like RN `wrapRow` — `min-w-0 shrink` lets text wrap
+         * inside a horizontal stack without forcing peers wide. In a vertical stack
+         * the `<p>` already fills its parent's width via `display: block`; avoid
+         * `flex-1` here because `flex-grow: 1` on a vertical-flex child fills the
+         * column's height, distributing siblings when the row is taller than its
+         * content (e.g. text next to a tall image).
+         */
+        inHorizontalStack ? "min-w-0 shrink" : "min-w-0",
       )}
       style={{ color: colors.text }}
     >

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

@@ -3,7 +3,7 @@ import { StyleSheet, Text, View, Pressable } from "react-native";
 import { useStateStore } from "@json-render/react-native";
 import { useSnapPalette } from "../use-snap-palette";
 import { useSnapTheme } from "../theme";
-import { POST_GRID_TAP_KEY } from "@farcaster/snap";
+import { POST_GRID_TAP_KEY, readableTextOnHex } from "@farcaster/snap";
 
 export function SnapCellGrid({
   element,
@@ -32,37 +32,50 @@ export function SnapCellGrid({
   const tapPath = `/inputs/${name}`;
   const tapRaw = get(tapPath);
 
+  const cellMap = new Map<
+    string,
+    { color?: string; content?: string; value?: string }
+  >();
+  for (const c of cells) {
+    cellMap.set(`${Number(c.row)},${Number(c.col)}`, {
+      color: c.color as string | undefined,
+      content: c.content != null ? String(c.content) : undefined,
+      value: typeof c.value === "string" ? c.value : undefined,
+    });
+  }
+
+  // Each cell's wire value — its `value` if set, otherwise "row,col" fallback.
+  const cellWireValue = (r: number, c: number) =>
+    cellMap.get(`${r},${c}`)?.value ?? `${r},${c}`;
+
+  // Multi mode joins values with `|`; single mode is the value itself.
   const selectedSet = new Set<string>();
   if (typeof tapRaw === "string" && tapRaw.length > 0) {
-    for (const part of tapRaw.split("|")) {
-      if (part.includes(",")) selectedSet.add(part);
+    if (isMultiple) {
+      for (const part of tapRaw.split("|")) {
+        if (part.length > 0) selectedSet.add(part);
+      }
+    } else {
+      selectedSet.add(tapRaw);
     }
   }
 
   const isSelected = (r: number, c: number) =>
-    isSelectable && selectedSet.has(`${r},${c}`);
+    isSelectable && selectedSet.has(cellWireValue(r, c));
 
   const handleTap = (r: number, c: number) => {
-    const key = `${r},${c}`;
+    const wire = cellWireValue(r, c);
     if (isMultiple) {
       const next = new Set(selectedSet);
-      if (next.has(key)) next.delete(key);
-      else next.add(key);
+      if (next.has(wire)) next.delete(wire);
+      else next.add(wire);
       set(tapPath, [...next].join("|"));
     } else {
-      set(tapPath, key);
+      set(tapPath, wire);
     }
     if (hasPressAction) emit("press");
   };
 
-  const cellMap = new Map<string, { color?: string; content?: string }>();
-  for (const c of cells) {
-    cellMap.set(`${Number(c.row)},${Number(c.col)}`, {
-      color: c.color as string | undefined,
-      content: c.content != null ? String(c.content) : undefined,
-    });
-  }
-
   const ringOuter = appearance === "dark" ? "#fff" : "#000";
   const ringInner = appearance === "dark" ? "#000" : "#fff";
 
@@ -76,10 +89,12 @@ export function SnapCellGrid({
     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) : emptyCellBg;
+      const bgHex = cell?.color ? hex(cell.color) : null;
+      const bg = bgHex ?? emptyCellBg;
+      const textColor = bgHex ? readableTextOnHex(bgHex) : colors.text;
 
       const cellContent = cell?.content ? (
-        <Text style={[styles.cellText, { color: colors.textPrimary }]}>
+        <Text style={[styles.cellText, { color: textColor }]}>
           {cell.content}
         </Text>
       ) : null;

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

@@ -3,6 +3,7 @@ import { Children, type ReactNode } from "react";
 import { StyleSheet, View } from "react-native";
 import {
   countRenderableChildren,
+  defaultHorizontalGapSize,
   horizontalChildrenAreAllButtons,
 } from "../../stack-horizontal-utils.js";
 import {
@@ -21,7 +22,7 @@ const HGAP: Record<string, number> = {
   none: 0,
   sm: 4,
   md: 8,
-  lg: 12,
+  lg: 16,
 };
 
 const JUSTIFY: Record<string, "flex-start" | "center" | "flex-end" | "space-between" | "space-around"> = {
@@ -53,12 +54,6 @@ export function SnapStack({
   const rawGap = props.gap;
   const isHorizontal = direction === "horizontal";
   const gapMap = isHorizontal ? HGAP : VGAP;
-  const gap =
-    typeof rawGap === "number"
-      ? rawGap
-      : typeof rawGap === "string" && rawGap in gapMap
-        ? gapMap[rawGap]!
-        : isHorizontal ? HGAP.md! : VGAP.md!;
   const buttonRowGrid =
     isHorizontal && horizontalChildrenAreAllButtons(children);
   const buttonRowCount = buttonRowGrid
@@ -73,6 +68,23 @@ export function SnapStack({
     Number.isInteger(columnsRaw)
       ? columnsRaw
       : undefined;
+
+  // Horizontal default depends on column count: 2→lg, 3→md, 4+→sm. Vertical stays md.
+  // Count comes from explicit `columns`, then button-row inference, else direct children
+  // count (any horizontal stack is N columns wide regardless of child types).
+  const horizontalColumnCount = isHorizontal
+    ? (columns ??
+       (buttonRowGrid ? buttonRowCount : undefined) ??
+       countRenderableChildren(children))
+    : undefined;
+  const gap =
+    typeof rawGap === "number"
+      ? rawGap
+      : typeof rawGap === "string" && rawGap in gapMap
+        ? gapMap[rawGap]!
+        : isHorizontal
+          ? gapMap[defaultHorizontalGapSize(horizontalColumnCount)]!
+          : VGAP.md!;
   const explicitColumnGrid =
     isHorizontal && columns !== undefined && !buttonRowGrid;
 

package/src/stack-horizontal-utils.ts

@@ -25,3 +25,17 @@ export function horizontalChildrenAreAllButtons(children: ReactNode): boolean {
 export function countRenderableChildren(children: ReactNode): number {
   return Children.toArray(children).filter(isRenderableChild).length;
 }
+
+/**
+ * Default horizontal stack gap as a t-shirt size, chosen by column count:
+ * 2 cols → lg, 3 cols → md, 4+ cols → sm. Unknown count falls back to md.
+ * Tighter gaps for denser layouts; authors can always override via the `gap` prop.
+ */
+export function defaultHorizontalGapSize(
+  columnCount: number | undefined,
+): "sm" | "md" | "lg" {
+  if (columnCount === undefined) return "md";
+  if (columnCount <= 2) return "lg";
+  if (columnCount === 3) return "md";
+  return "sm";
+}

package/src/ui/cell-grid.ts

@@ -26,6 +26,7 @@ const cellGridCellSchema = z.object({
   col: z.number().int().nonnegative(),
   color: cellGridCellColorSchema.optional(),
   content: z.string().optional(),
+  value: z.string().min(1).max(30).optional(),
 });
 
 export const cellGridProps = z