@farcaster/snap 1.4.1 → 1.5.1

package/dist/schemas.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { BAR_CHART_COLOR_VALUES, BUTTON_ACTION, BUTTON_ACTION_VALUES, BUTTON_GROUP_STYLE, BUTTON_GROUP_STYLE_VALUES, BUTTON_LAYOUT_VALUES, BUTTON_STYLE_VALUES, DEFAULT_BUTTON_LAYOUT, DEFAULT_LIST_STYLE, DEFAULT_SLIDER_STEP, DEFAULT_THEME_ACCENT, EFFECT_VALUES, ELEMENT_TYPE, GRID_CELL_SIZE_VALUES, GRID_GAP_VALUES, GROUP_LAYOUT_VALUES, HEX_COLOR_6_RE, HTTP_PREFIX, HTTPS_PREFIX, IMAGE_ASPECT_VALUES, INTERACTIVE_ELEMENT_TYPES, LIMITS, LIST_STYLE_VALUES, MEDIA_ELEMENT_TYPES, PAGE_ROOT_TYPE, PALETTE_COLOR_VALUES, PROGRESS_COLOR_VALUES, SLIDER_STEP_ALIGN_EPS, SPACER_SIZE, SPACER_SIZE_VALUES, SPEC_VERSION, TEXT_ALIGN_VALUES, TEXT_CONTENT_MAX, TEXT_STYLE, TEXT_STYLE_VALUES, } from "./constants.js";
+import { BUTTON_ACTION, BUTTON_ACTION_VALUES, CLIENT_ACTION, BUTTON_GROUP_STYLE, BUTTON_GROUP_STYLE_VALUES, BUTTON_LAYOUT_VALUES, BUTTON_STYLE_VALUES, DEFAULT_BUTTON_LAYOUT, DEFAULT_GRID_GAP, DEFAULT_LIST_STYLE, DEFAULT_SLIDER_STEP, EFFECT_VALUES, ELEMENT_TYPE, GRID_CELL_SIZE_VALUES, GRID_GAP_VALUES, GROUP_LAYOUT_VALUES, HEX_COLOR_6_RE, HTTP_PREFIX, HTTPS_PREFIX, IMAGE_ASPECT_VALUES, INTERACTIVE_ELEMENT_TYPES, LIMITS, LIST_STYLE_VALUES, MEDIA_ELEMENT_TYPES, PAGE_ROOT_TYPE, SLIDER_STEP_ALIGN_EPS, SPACER_SIZE, SPACER_SIZE_VALUES, SPEC_VERSION, TEXT_ALIGN_VALUES, TEXT_CONTENT_MAX, TEXT_STYLE, TEXT_STYLE_VALUES, } from "./constants.js";
+import { BAR_CHART_COLOR_VALUES, DEFAULT_THEME_ACCENT, PALETTE_COLOR_VALUES, PROGRESS_COLOR_VALUES, } from "./colors.js";
 /**
  * post/link/mini_app targets must be HTTPS in production; allow HTTP only for
  * loopback hosts so local snap servers (e.g. http://localhost:3014/snap) validate.
@@ -28,25 +29,8 @@ const themeSchema = z
     accent: themeAccentSchema.default(DEFAULT_THEME_ACCENT),
 })
     .strict();
-const httpsUrl = z.string().refine((s) => s.startsWith(HTTPS_PREFIX), {
-    message: "URL must use HTTPS",
-});
-function hasAllowedMediaExtension(urlString, allowedExtensions) {
-    try {
-        const url = new URL(urlString);
-        if (url.protocol !== "https:")
-            return false;
-        const lowerPathname = url.pathname.toLowerCase();
-        return allowedExtensions.some((extension) => lowerPathname.endsWith(`.${extension}`));
-    }
-    catch {
-        return false;
-    }
-}
-const imageUrlSchema = z
-    .string()
-    .refine((s) => hasAllowedMediaExtension(s, ["jpg", "png", "gif", "webp"]), {
-    message: "image URL must use HTTPS and end with a supported extension (.jpg, .png, .gif, .webp)",
+const imageUrlSchema = z.string().refine((s) => s.startsWith(HTTPS_PREFIX), {
+    message: "image URL must use HTTPS",
 });
 const textAlignSchema = z.enum(TEXT_ALIGN_VALUES);
 const textElementSchema = z
@@ -152,7 +136,7 @@ const gridElementSchema = z
     rows: z.number().int().min(LIMITS.minGridRows).max(LIMITS.maxGridRows),
     cells: z.array(gridCellSchema),
     cellSize: z.enum(GRID_CELL_SIZE_VALUES).optional(),
-    gap: z.enum(GRID_GAP_VALUES).optional(),
+    gap: z.enum(GRID_GAP_VALUES).default(DEFAULT_GRID_GAP),
     interactive: z.boolean().optional(),
 })
     .superRefine((val, ctx) => {
@@ -300,24 +284,134 @@ const barChartElementSchema = z
 });
 const buttonActionSchema = z.enum(BUTTON_ACTION_VALUES);
 const buttonStyleSchema = z.enum(BUTTON_STYLE_VALUES);
+/* ------------------------------------------------------------------ */
+/*  Client action schemas                                              */
+/* ------------------------------------------------------------------ */
+const viewCastClientActionSchema = z
+    .object({
+    type: z.literal(CLIENT_ACTION.view_cast),
+    hash: z.string().min(1),
+})
+    .strict();
+const viewProfileClientActionSchema = z
+    .object({
+    type: z.literal(CLIENT_ACTION.view_profile),
+    fid: z.number().int().nonnegative(),
+})
+    .strict();
+const composeCastClientActionSchema = z
+    .object({
+    type: z.literal(CLIENT_ACTION.compose_cast),
+    text: z.string().optional(),
+    embeds: z
+        .array(z.string())
+        .max(2, { message: "compose_cast embeds: max 2 URLs" })
+        .optional(),
+    parent: z
+        .object({
+        type: z.literal("cast"),
+        hash: z.string().min(1),
+    })
+        .strict()
+        .optional(),
+    channelKey: z.string().optional(),
+})
+    .strict();
+const viewTokenClientActionSchema = z
+    .object({
+    type: z.literal(CLIENT_ACTION.view_token),
+    /** CAIP-19 asset ID (e.g. "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913") */
+    token: z.string().min(1),
+})
+    .strict();
+const sendTokenClientActionSchema = z
+    .object({
+    type: z.literal(CLIENT_ACTION.send_token),
+    /** CAIP-19 asset ID */
+    token: z.string().optional(),
+    /** Amount in raw token units (e.g. "1000000" for 1 USDC) */
+    amount: z.string().optional(),
+    recipientFid: z.number().int().nonnegative().optional(),
+    recipientAddress: z.string().optional(),
+})
+    .strict();
+const swapTokenClientActionSchema = z
+    .object({
+    type: z.literal(CLIENT_ACTION.swap_token),
+    /** CAIP-19 asset ID to sell */
+    sellToken: z.string().optional(),
+    /** CAIP-19 asset ID to buy */
+    buyToken: z.string().optional(),
+    /** Amount in raw token units */
+    sellAmount: z.string().optional(),
+})
+    .strict();
+export const clientActionSchema = z.discriminatedUnion("type", [
+    viewCastClientActionSchema,
+    viewProfileClientActionSchema,
+    composeCastClientActionSchema,
+    viewTokenClientActionSchema,
+    sendTokenClientActionSchema,
+    swapTokenClientActionSchema,
+]);
+/* ------------------------------------------------------------------ */
+/*  Button schema                                                      */
+/* ------------------------------------------------------------------ */
 const buttonSchema = z
     .object({
     label: z.string().min(1).max(LIMITS.maxButtonLabelChars),
     action: buttonActionSchema,
-    /** URL (HTTPS for post/link/mini_app) or SDK action id (e.g. cast:view:...) */
-    target: z.string().min(1),
+    /** URL target for post/link/mini_app buttons */
+    target: z.string().min(1).optional(),
+    /** Structured client action for client buttons */
+    client_action: clientActionSchema.optional(),
     style: buttonStyleSchema.optional(),
 })
     .superRefine((val, ctx) => {
-    if ((val.action === BUTTON_ACTION.post ||
-        val.action === BUTTON_ACTION.link ||
-        val.action === BUTTON_ACTION.mini_app) &&
-        !isSecureOrLoopbackHttpButtonTarget(val.target)) {
-        ctx.addIssue({
-            code: "custom",
-            message: `button target must use HTTPS (or http:// on localhost / 127.0.0.1 for development) for action "${val.action}" (received: ${val.target})`,
-            path: ["target"],
-        });
+    if (val.action === BUTTON_ACTION.client) {
+        // client buttons require client_action, must not have target
+        if (val.client_action === undefined) {
+            ctx.addIssue({
+                code: "custom",
+                message: `button with action "client" must include a "client_action" object`,
+                path: ["client_action"],
+            });
+        }
+        if (val.target !== undefined) {
+            ctx.addIssue({
+                code: "custom",
+                message: `button with action "client" must not include "target"`,
+                path: ["target"],
+            });
+        }
+    }
+    else {
+        // post/link/mini_app buttons require target, must not have client_action
+        if (val.target === undefined) {
+            ctx.addIssue({
+                code: "custom",
+                message: `button with action "${val.action}" must include a "target" URL`,
+                path: ["target"],
+            });
+        }
+        if (val.client_action !== undefined) {
+            ctx.addIssue({
+                code: "custom",
+                message: `button with action "${val.action}" must not include "client_action"`,
+                path: ["client_action"],
+            });
+        }
+        if (val.target &&
+            (val.action === BUTTON_ACTION.post ||
+                val.action === BUTTON_ACTION.link ||
+                val.action === BUTTON_ACTION.mini_app) &&
+            !isSecureOrLoopbackHttpButtonTarget(val.target)) {
+            ctx.addIssue({
+                code: "custom",
+                message: `button target must use HTTPS (or http:// on localhost / 127.0.0.1 for development) for action "${val.action}" (received: ${val.target})`,
+                path: ["target"],
+            });
+        }
     }
 });
 /** Child elements allowed inside `group` (no media, no nested group) */
@@ -457,3 +551,17 @@ export const snapActionSchema = z.discriminatedUnion("type", [
     snapGetActionSchema,
     snapPostActionSchema,
 ]);
+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);
+        },
+    };
+}

package/dist/server/parseRequest.d.ts

@@ -21,6 +21,12 @@ export type ParseRequestOptions = {
      * When true, skip {@link verifyJFSRequestBody} (signature checks).
      */
     skipJFSVerification?: boolean;
+    /**
+     * Maximum allowed absolute difference between the request timestamp and the
+     * server clock, in seconds. Requests outside this window are rejected as
+     * potential replays. Defaults to 300 (5 minutes) when not provided.
+     */
+    maxSkewSeconds?: number;
 };
 export type ParseRequestResult = {
     success: true;

package/dist/server/parseRequest.js

@@ -1,7 +1,6 @@
 import { ACTION_TYPE_GET, ACTION_TYPE_POST, payloadSchema, } from "../schemas.js";
 import { decodePayload, verifyJFSRequestBody } from "./verify.js";
 import { z } from "zod";
-/** Default replay window per SPEC.md § Replay Protection (5 minutes). */
 const DEFAULT_SNAP_POST_MAX_SKEW_SECONDS = 300;
 const requestBodySchema = z.object({
     header: z.string(),
@@ -29,7 +28,7 @@ export async function parseRequest(request, options = {}) {
             action: { type: ACTION_TYPE_GET },
         };
     }
-    const maxSkew = DEFAULT_SNAP_POST_MAX_SKEW_SECONDS;
+    const maxSkew = options.maxSkewSeconds ?? DEFAULT_SNAP_POST_MAX_SKEW_SECONDS;
     const nowSec = Math.floor(Date.now() / 1000);
     const text = await request.text();
     let jsonBody;

package/dist/ui/bar-chart.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { BAR_CHART_COLOR_VALUES, LIMITS, PALETTE_COLOR_VALUES, } from "../constants.js";
+import { LIMITS } from "../constants.js";
+import { BAR_CHART_COLOR_VALUES, PALETTE_COLOR_VALUES } from "../colors.js";
 export const barChartProps = z.object({
     bars: z
         .array(z.object({

package/dist/ui/button-group.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-export declare const buttonGroupProps: z.ZodObject<{
+export declare const buttonGroupProps: z.ZodPipe<z.ZodObject<{
     name: z.ZodString;
     options: z.ZodArray<z.ZodString>;
     style: z.ZodOptional<z.ZodEnum<{
@@ -7,5 +7,13 @@ export declare const buttonGroupProps: z.ZodObject<{
         stack: "stack";
         grid: "grid";
     }>>;
-}, z.core.$strip>;
+}, z.core.$strip>, z.ZodTransform<{
+    style: "row" | "stack" | "grid";
+    name: string;
+    options: string[];
+}, {
+    name: string;
+    options: string[];
+    style?: "row" | "stack" | "grid" | undefined;
+}>>;
 export type ButtonGroupProps = z.infer<typeof buttonGroupProps>;

package/dist/ui/button-group.js

@@ -1,10 +1,18 @@
 import { z } from "zod";
-import { BUTTON_GROUP_STYLE_VALUES, LIMITS } from "../constants.js";
-export const buttonGroupProps = z.object({
+import { BUTTON_GROUP_STYLE, BUTTON_GROUP_STYLE_VALUES, LIMITS, } from "../constants.js";
+export const buttonGroupProps = z
+    .object({
     name: z.string().min(1),
     options: z
-        .array(z.string())
+        .array(z.string().max(LIMITS.maxButtonGroupOptionChars))
         .min(LIMITS.minButtonGroupOptions)
         .max(LIMITS.maxButtonGroupOptions),
     style: z.enum(BUTTON_GROUP_STYLE_VALUES).optional(),
-});
+})
+    .transform((val) => ({
+    ...val,
+    style: val.style ??
+        (val.options.length <= 3
+            ? BUTTON_GROUP_STYLE.row
+            : BUTTON_GROUP_STYLE.stack),
+}));

package/dist/ui/button.d.ts

@@ -5,9 +5,10 @@ export declare const actionButtonProps: z.ZodObject<{
         post: "post";
         link: "link";
         mini_app: "mini_app";
-        sdk: "sdk";
+        client: "client";
     }>;
-    target: z.ZodString;
+    target: z.ZodOptional<z.ZodString>;
+    client_action: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     style: z.ZodOptional<z.ZodEnum<{
         primary: "primary";
         secondary: "secondary";
@@ -21,9 +22,10 @@ export declare const buttonProps: z.ZodObject<{
         post: "post";
         link: "link";
         mini_app: "mini_app";
-        sdk: "sdk";
+        client: "client";
     }>;
-    target: z.ZodString;
+    target: z.ZodOptional<z.ZodString>;
+    client_action: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     style: z.ZodOptional<z.ZodEnum<{
         primary: "primary";
         secondary: "secondary";

package/dist/ui/button.js

@@ -3,7 +3,8 @@ import { BUTTON_ACTION_VALUES, BUTTON_STYLE_VALUES } from "../constants.js";
 export const actionButtonProps = z.object({
     label: z.string(),
     action: z.enum(BUTTON_ACTION_VALUES),
-    target: z.string(),
+    target: z.string().optional(),
+    client_action: z.record(z.string(), z.unknown()).optional(),
     style: z.enum(BUTTON_STYLE_VALUES).optional(),
 });
 /** Same schema as `actionButtonProps` (legacy export name). */

package/dist/ui/catalog.d.ts

@@ -69,7 +69,7 @@ export declare const snapJsonRenderCatalog: import("@json-render/core").Catalog<
         };
         Spacer: {
             props: z.ZodObject<{
-                size: z.ZodOptional<z.ZodEnum<{
+                size: z.ZodDefault<z.ZodEnum<{
                     small: "small";
                     medium: "medium";
                     large: "large";
@@ -155,7 +155,7 @@ export declare const snapJsonRenderCatalog: import("@json-render/core").Catalog<
             description: string;
         };
         ButtonGroup: {
-            props: z.ZodObject<{
+            props: z.ZodPipe<z.ZodObject<{
                 name: z.ZodString;
                 options: z.ZodArray<z.ZodString>;
                 style: z.ZodOptional<z.ZodEnum<{
@@ -163,14 +163,22 @@ export declare const snapJsonRenderCatalog: import("@json-render/core").Catalog<
                     stack: "stack";
                     grid: "grid";
                 }>>;
-            }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodTransform<{
+                style: "row" | "stack" | "grid";
+                name: string;
+                options: string[];
+            }, {
+                name: string;
+                options: string[];
+                style?: "row" | "stack" | "grid" | undefined;
+            }>>;
             description: string;
         };
         Toggle: {
             props: z.ZodObject<{
                 name: z.ZodString;
                 label: z.ZodString;
-                value: z.ZodOptional<z.ZodBoolean>;
+                value: z.ZodDefault<z.ZodBoolean>;
             }, z.core.$strip>;
             description: string;
         };
@@ -209,7 +217,6 @@ export declare const snapJsonRenderCatalog: import("@json-render/core").Catalog<
             props: z.ZodObject<{
                 layout: z.ZodEnum<{
                     row: "row";
-                    grid: "grid";
                 }>;
             }, z.core.$strip>;
             description: string;
@@ -225,9 +232,10 @@ export declare const snapJsonRenderCatalog: import("@json-render/core").Catalog<
                     post: "post";
                     link: "link";
                     mini_app: "mini_app";
-                    sdk: "sdk";
+                    client: "client";
                 }>;
-                target: z.ZodString;
+                target: z.ZodOptional<z.ZodString>;
+                client_action: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
                 style: z.ZodOptional<z.ZodEnum<{
                     primary: "primary";
                     secondary: "secondary";
@@ -261,10 +269,10 @@ export declare const snapJsonRenderCatalog: import("@json-render/core").Catalog<
                 target: z.ZodString;
             }, z.core.$strip>;
         };
-        snap_sdk: {
+        snap_client: {
             description: string;
             params: z.ZodObject<{
-                target: z.ZodString;
+                client_action: z.ZodRecord<z.ZodString, z.ZodUnknown>;
             }, z.core.$strip>;
         };
     };

package/dist/ui/catalog.js

@@ -26,6 +26,9 @@ const snapPostParams = z.object({
 const snapTargetParams = z.object({
     target: z.string(),
 });
+const snapClientParams = z.object({
+    client_action: z.record(z.string(), z.unknown()),
+});
 /**
  * Basic catalog: one json-render component per snap element type, plus ActionButton for snap buttons.
  * Does not validate cross-field rules (media count, height budget); snap JSON still goes through `@farcaster/snap` validation.
@@ -90,7 +93,7 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
         },
         ActionButton: {
             props: actionButtonProps,
-            description: "Snap action button: post (next page), link (browser), mini_app, sdk — target is HTTPS URL or SDK id.",
+            description: "Snap action button: post (next page), link (browser), mini_app, client — target is HTTPS URL or client_action object.",
         },
     },
     actions: {
@@ -106,9 +109,9 @@ export const snapJsonRenderCatalog = defineCatalog(snapJsonRenderSchema, {
             description: "Open `target` as an in-app Farcaster mini app.",
             params: snapTargetParams,
         },
-        snap_sdk: {
-            description: "Run a Farcaster client SDK action (cast:view, user:follow, …).",
-            params: snapTargetParams,
+        snap_client: {
+            description: "Trigger a Farcaster client action (view_cast, view_profile, compose_cast, …).",
+            params: snapClientParams,
         },
     },
 });

package/dist/ui/group.d.ts

@@ -2,7 +2,6 @@ import { z } from "zod";
 export declare const groupProps: z.ZodObject<{
     layout: z.ZodEnum<{
         row: "row";
-        grid: "grid";
     }>;
 }, z.core.$strip>;
 export type GroupProps = z.infer<typeof groupProps>;

package/dist/ui/group.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { GROUP_LAYOUT_VALUES } from "../constants.js";
 export const groupProps = z.object({
-    layout: z.enum(["row", "grid"]),
+    layout: z.enum(GROUP_LAYOUT_VALUES),
 });

package/dist/ui/progress.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { PROGRESS_COLOR_VALUES } from "../constants.js";
+import { PROGRESS_COLOR_VALUES } from "../colors.js";
 export const progressProps = z.object({
     value: z.number(),
     max: z.number(),

package/dist/ui/schema.js

@@ -26,6 +26,6 @@ export const snapJsonRenderSchema = defineSchema((s) => ({
     defaultRules: [
         "You are generating auxiliary UI for a Farcaster Snap. Prefer components matching snap element types (Text, Image, ButtonGroup, …).",
         "Snap pages use a Stack root with at most 5 body children and 1 media element (Image or Grid); keep generated trees small.",
-        "Bottom-of-card snap buttons are ActionButton components; use actions post / link / mini_app / sdk per SPEC.md.",
+        "Bottom-of-card snap buttons are ActionButton components; use actions post / link / mini_app / client.",
     ],
 });

package/dist/ui/spacer.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 export declare const spacerProps: z.ZodObject<{
-    size: z.ZodOptional<z.ZodEnum<{
+    size: z.ZodDefault<z.ZodEnum<{
         small: "small";
         medium: "medium";
         large: "large";

package/dist/ui/spacer.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { SPACER_SIZE_VALUES } from "../constants.js";
+import { SPACER_SIZE, SPACER_SIZE_VALUES } from "../constants.js";
 export const spacerProps = z.object({
-    size: z.enum(SPACER_SIZE_VALUES).optional(),
+    size: z.enum(SPACER_SIZE_VALUES).default(SPACER_SIZE.medium),
 });

package/dist/ui/toggle.d.ts

@@ -2,6 +2,6 @@ import { z } from "zod";
 export declare const toggleProps: z.ZodObject<{
     name: z.ZodString;
     label: z.ZodString;
-    value: z.ZodOptional<z.ZodBoolean>;
+    value: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 export type ToggleProps = z.infer<typeof toggleProps>;

package/dist/ui/toggle.js

@@ -2,5 +2,5 @@ import { z } from "zod";
 export const toggleProps = z.object({
     name: z.string().min(1),
     label: z.string(),
-    value: z.boolean().optional(),
+    value: z.boolean().default(false),
 });

package/package.json

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

package/src/colors.ts

@@ -0,0 +1,73 @@
+/**
+ * Named color palette for snaps. Snap authors specify a name; the client maps
+ * it to a hex value appropriate for its current light/dark mode.
+ *
+ * Light-mode hex values (used by emulator):
+ *   gray=#8F8F8F  blue=#006BFF  red=#FC0036  amber=#FFAE00
+ *   green=#28A948  teal=#00AC96  purple=#8B5CF6  pink=#F32782
+ *
+ * Dark-mode hex values (for reference; client-owned):
+ *   gray=#8F8F8F  blue=#006FFE  red=#F13342  amber=#FFAE00
+ *   green=#00AC3A  teal=#00AA96  purple=#A78BFA  pink=#F12B82
+ */
+export const PALETTE_COLOR = {
+  gray: "gray",
+  blue: "blue",
+  red: "red",
+  amber: "amber",
+  green: "green",
+  teal: "teal",
+  purple: "purple",
+  pink: "pink",
+} as const;
+
+export const PALETTE_COLOR_ACCENT = "accent" as const;
+
+export const DEFAULT_THEME_ACCENT = PALETTE_COLOR.purple;
+
+export const PALETTE_COLOR_VALUES = [
+  PALETTE_COLOR.gray,
+  PALETTE_COLOR.blue,
+  PALETTE_COLOR.red,
+  PALETTE_COLOR.amber,
+  PALETTE_COLOR.green,
+  PALETTE_COLOR.teal,
+  PALETTE_COLOR.purple,
+  PALETTE_COLOR.pink,
+] as const;
+
+export type PaletteColor = (typeof PALETTE_COLOR_VALUES)[number];
+
+/** Light-mode hex for each palette color (emulator / reference client). */
+export const PALETTE_LIGHT_HEX: Record<PaletteColor, string> = {
+  gray: "#8F8F8F",
+  blue: "#006BFF",
+  red: "#FC0036",
+  amber: "#FFAE00",
+  green: "#28A948",
+  teal: "#00AC96",
+  purple: "#8B5CF6",
+  pink: "#F32782",
+};
+
+/** Dark-mode hex for each palette color (reference). */
+export const PALETTE_DARK_HEX: Record<PaletteColor, string> = {
+  gray: "#8F8F8F",
+  blue: "#006FFE",
+  red: "#F13342",
+  amber: "#FFAE00",
+  green: "#00AC3A",
+  teal: "#00AA96",
+  purple: "#A78BFA",
+  pink: "#F12B82",
+};
+
+export const PROGRESS_COLOR_VALUES = [
+  PALETTE_COLOR_ACCENT,
+  ...PALETTE_COLOR_VALUES,
+] as const;
+
+export const BAR_CHART_COLOR_VALUES = [
+  PALETTE_COLOR_ACCENT,
+  ...PALETTE_COLOR_VALUES,
+] as const;