Support dynamic client action params

* chore: start NEYN-12016 snap education work

* Support dynamic client action params

* Add dynamic client params changeset

* Keep submit action targets literal

Author: bob-obringer

.changeset/lemon-tips-roll.md

@@ -0,0 +1,5 @@
+---
+"@farcaster/snap": minor
+---
+
+Add dynamic client action params

apps/docs/src/app/(docs)/2.0/(clients)/client-rendering/page.mdx

@@ -103,6 +103,12 @@ input values from `input`, `slider`, `switch`, and `toggle_group` elements are
 automatically collected and passed as the `inputs` parameter. See
 [Upgrading from v1.0](/snap/client-upgrade) for the POST payload format.
 
+Client action params are resolved from the current local render state before the
+handler is called. For example, an `open_url` button can use
+`target: { "$template": "https://example.com/?q=${/inputs/query}" }`; the handler
+still receives a plain string target after resolution. Clients must validate resolved
+URL targets before opening them.
+
 ## Full Example
 
 This example shows the complete flow: rendering a snap, handling submit with a signed

apps/docs/src/app/(docs)/2.0/(spec)/actions/page.mdx

@@ -65,11 +65,14 @@ field (`standalone` vs `cast`).
 
 ## open_url
 
-Open a URL in the system browser. No server round-trip. No input collection.
+Open a URL in the system browser. No server round-trip. No POST payload.
 
-| Param    | Type   | Required | Description |
-| -------- | ------ | -------- | ----------- |
-| `target` | string | Yes      | URL to open |
+`params.target` may be a literal URL or a dynamic string resolved from local render
+state at tap time. Field values are available under `/inputs/<name>`.
+
+| Param    | Type                    | Required | Description |
+| -------- | ----------------------- | -------- | ----------- |
+| `target` | string \| dynamic string | Yes      | URL to open |
 
 ```json
 {
@@ -84,6 +87,27 @@ Open a URL in the system browser. No server round-trip. No input collection.
 }
 ```
 
+```json
+{
+  "type": "button",
+  "props": { "label": "Start Audit", "icon": "external-link" },
+  "on": {
+    "press": {
+      "action": "open_url",
+      "params": {
+        "target": {
+          "$template": "https://example.com/audit?nsite=${/inputs/website}"
+        }
+      }
+    }
+  }
+}
+```
+
+Dynamic targets are resolved by the client before opening. The resolved URL must still
+pass the normal URL rules: HTTPS in production, loopback HTTP for local development,
+and no `javascript:` URLs.
+
 ---
 
 ## open_snap
@@ -206,11 +230,15 @@ Navigate to a Farcaster channel.
 
 Open the cast composer with optional pre-filled content.
 
-| Param        | Type     | Required | Description               |
-| ------------ | -------- | -------- | ------------------------- |
-| `text`       | string   | No       | Pre-filled cast text      |
-| `channelKey` | string   | No       | Target channel key        |
-| `embeds`     | string[] | No       | URLs to embed in the cast |
+Text-like params may be dynamic strings resolved from local render state. For example,
+`text: { "$state": "/inputs/castText" }` opens the composer with the current input
+value.
+
+| Param        | Type                    | Required | Description               |
+| ------------ | ----------------------- | -------- | ------------------------- |
+| `text`       | string \| dynamic string | No       | Pre-filled cast text      |
+| `channelKey` | string \| dynamic string | No       | Target channel key        |
+| `embeds`     | string[]                | No       | URLs to embed in the cast |
 
 > Put URLs in `embeds`, not in `text`.
 

apps/docs/src/app/(docs)/2.0/(spec)/buttons/page.mdx

@@ -93,6 +93,11 @@ production.
 For local development, `http://` is valid only when the host is loopback: `localhost`,
 `127.0.0.1`, or IPv6 loopback (`[::1]` / `::1`).
 
+For client actions such as `open_url`, `open_mini_app`, and `compose_cast`, action
+params may be dynamic strings resolved from local render state when the button is
+tapped. Field values are available under `/inputs/<name>`, so a button can open a URL
+that includes the current value of an input without sending a POST request.
+
 ## Input Data in POST Requests
 
 When a `submit` action fires, the client collects values from all field components on

apps/docs/src/app/(docs)/2.0/(spec)/constraints/page.mdx

@@ -86,3 +86,6 @@ development and emulators, **`http://` is allowed** when the host is loopback on
 targets are invalid.
 
 No `javascript:` URIs.
+
+Dynamic action targets are resolved by the client before the action runs. The resolved
+URL must pass the same URL rules before the client opens it.

apps/docs/src/app/(docs)/2.0/(spec)/spec-overview/page.mdx

@@ -19,10 +19,13 @@ Example interaction:
 3. The client renders the `ui` tree using the component catalog
 4. The user interacts with field components (`input`, `slider`, `switch`,
    `toggle_group`) — values are stored locally
-5. The user taps a `button` element whose `on.press` is bound to a `submit` action
-6. The client collects all field values and POSTs a signed payload to the `target` URL
-7. The server returns a new SnapResponse — the client renders it as the next page
-8. Repeat
+5. The user taps a `button` element whose `on.press` is bound to an action
+6. For a `submit` action, the client collects all field values and POSTs a signed
+   payload to the `target` URL
+7. For a client action, the client may resolve params from local state and perform the
+   action without a POST
+8. If the action returns a new SnapResponse, the client renders it as the next page
+9. Repeat
 
 ## Content Negotiation
 

pkgs/snap/src/react-native/snap-view-core.tsx

@@ -28,6 +28,9 @@ import {
   getUnpresentedSnapEffects,
   hasPendingSnapAction,
   markSnapEffectsPresented,
+  optionalSnapStringArray,
+  resolveSnapActionParamsForAction,
+  validateSnapActionTargetUrl,
   type SnapRenderState,
 } from "../render-state";
 import type { SnapPage, SnapActionHandlers, JsonValue } from "./types";
@@ -42,6 +45,15 @@ function optionalString(value: unknown): string | undefined {
   return value ? String(value) : undefined;
 }
 
+function validActionTarget(value: unknown): string | undefined {
+  const target = String(value ?? "");
+  return validateSnapActionTargetUrl(target) ? undefined : target;
+}
+
+function literalStringParam(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
 function recordValue(value: unknown): Record<string, unknown> | undefined {
   return value && typeof value === "object" && !Array.isArray(value)
     ? (value as Record<string, unknown>)
@@ -259,25 +271,31 @@ export function SnapViewCoreInner({
   );
 
   const handleAction = useCallback((name: unknown, params: unknown) => {
+    const p = resolveSnapActionParamsForAction(name, params, stateRef.current);
     const inputs = (stateRef.current.inputs ?? {}) as Record<string, JsonValue>;
-    const p = (params ?? {}) as Record<string, unknown>;
     const h = handlersRef.current;
     let result: unknown;
     setActionPending(name, p);
 
     switch (name) {
       case "submit":
-        result = h.submit(String(p.target ?? ""), inputs);
+        result = h.submit(literalStringParam(p.target), inputs);
         break;
-      case "open_url":
-        result = h.open_url(String(p.target ?? ""));
+      case "open_url": {
+        const target = validActionTarget(p.target);
+        if (target) result = h.open_url(target);
         break;
-      case "open_snap":
-        result = h.open_snap(String(p.target ?? ""));
+      }
+      case "open_snap": {
+        const target = validActionTarget(p.target);
+        if (target) result = h.open_snap(target);
         break;
-      case "open_mini_app":
-        result = h.open_mini_app(String(p.target ?? ""));
+      }
+      case "open_mini_app": {
+        const target = validActionTarget(p.target);
+        if (target) result = h.open_mini_app(target);
         break;
+      }
       case "view_cast":
         result = h.view_cast({ hash: String(p.hash ?? "") });
         break;
@@ -291,7 +309,7 @@ export function SnapViewCoreInner({
         result = h.compose_cast({
           text: p.text ? String(p.text) : undefined,
           channelKey: p.channelKey ? String(p.channelKey) : undefined,
-          embeds: Array.isArray(p.embeds) ? (p.embeds as string[]) : undefined,
+          embeds: optionalSnapStringArray(p.embeds),
         });
         break;
       case "view_token":

pkgs/snap/src/react/snap-view-core.tsx

@@ -15,6 +15,9 @@ import {
   getUnpresentedSnapEffects,
   hasPendingSnapAction,
   markSnapEffectsPresented,
+  optionalSnapStringArray,
+  resolveSnapActionParamsForAction,
+  validateSnapActionTargetUrl,
   type SnapRenderState,
 } from "../render-state";
 import {
@@ -38,6 +41,15 @@ function optionalString(value: unknown): string | undefined {
   return value ? String(value) : undefined;
 }
 
+function validActionTarget(value: unknown): string | undefined {
+  const target = String(value ?? "");
+  return validateSnapActionTargetUrl(target) ? undefined : target;
+}
+
+function literalStringParam(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
 function recordValue(value: unknown): Record<string, unknown> | undefined {
   return value && typeof value === "object" && !Array.isArray(value)
     ? (value as Record<string, unknown>)
@@ -543,27 +555,37 @@ export function SnapViewCore({
 
   const handleAction = useCallback(
     (name: unknown, params: unknown) => {
+      const p = resolveSnapActionParamsForAction(
+        name,
+        params,
+        stateRef.current,
+      );
       const inputs = (stateRef.current.inputs ?? {}) as Record<
         string,
         JsonValue
       >;
-      const p = (params ?? {}) as Record<string, unknown>;
       let result: unknown;
       setActionPending(name, p);
 
       switch (name) {
         case "submit":
-          result = handlers.submit(String(p.target ?? ""), inputs);
+          result = handlers.submit(literalStringParam(p.target), inputs);
           break;
-        case "open_url":
-          result = handlers.open_url(String(p.target ?? ""));
+        case "open_url": {
+          const target = validActionTarget(p.target);
+          if (target) result = handlers.open_url(target);
           break;
-        case "open_snap":
-          result = handlers.open_snap(String(p.target ?? ""));
+        }
+        case "open_snap": {
+          const target = validActionTarget(p.target);
+          if (target) result = handlers.open_snap(target);
           break;
-        case "open_mini_app":
-          result = handlers.open_mini_app(String(p.target ?? ""));
+        }
+        case "open_mini_app": {
+          const target = validActionTarget(p.target);
+          if (target) result = handlers.open_mini_app(target);
           break;
+        }
         case "view_cast":
           result = handlers.view_cast({ hash: String(p.hash ?? "") });
           break;
@@ -579,9 +601,7 @@ export function SnapViewCore({
           result = handlers.compose_cast({
             text: p.text ? String(p.text) : undefined,
             channelKey: p.channelKey ? String(p.channelKey) : undefined,
-            embeds: Array.isArray(p.embeds)
-              ? (p.embeds as string[])
-              : undefined,
+            embeds: optionalSnapStringArray(p.embeds),
           });
           break;
         case "view_token":

pkgs/snap/src/render-state.ts

@@ -1,3 +1,5 @@
+import { resolveActionParam } from "@json-render/core";
+
 export type SnapRenderState = Record<string, unknown>;
 
 export type SnapRenderStateChanges =
@@ -13,6 +15,31 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function isLoopback(url: URL): boolean {
+  const host = url.hostname;
+  return (
+    host === "localhost" ||
+    host === "127.0.0.1" ||
+    host === "::1" ||
+    host === "[::1]"
+  );
+}
+
+export function validateSnapActionTargetUrl(raw: string): string | null {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return `Invalid URL: "${raw}"`;
+  }
+
+  if (url.protocol === "https:") return null;
+  if (url.protocol === "http:" && isLoopback(url)) return null;
+  if (url.protocol === "javascript:") return `javascript: URIs are not allowed`;
+
+  return `URL must use HTTPS (got ${url.protocol.replace(":", "")}): "${raw}"`;
+}
+
 function normalizeEffects(effects: readonly string[] | undefined): string[] {
   if (!effects) return [];
 
@@ -158,6 +185,38 @@ export function buildActionActivityStateChanges({
   ];
 }
 
+export function resolveSnapActionParams(
+  params: unknown,
+  state: SnapRenderState,
+): Record<string, unknown> {
+  const actionParams = getSnapActionParams(params);
+
+  const resolved: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(actionParams)) {
+    resolved[key] = resolveActionParam(value, { stateModel: state });
+  }
+  return resolved;
+}
+
+export function getSnapActionParams(params: unknown): Record<string, unknown> {
+  if (!isRecord(params)) return {};
+  return cloneSnapRenderState(params);
+}
+
+export function resolveSnapActionParamsForAction(
+  actionName: unknown,
+  params: unknown,
+  state: SnapRenderState,
+): Record<string, unknown> {
+  if (actionName === "submit") return getSnapActionParams(params);
+  return resolveSnapActionParams(params, state);
+}
+
+export function optionalSnapStringArray(value: unknown): string[] | undefined {
+  if (Array.isArray(value)) return value.map((item) => String(item));
+  return value ? [String(value)] : undefined;
+}
+
 export function hasPendingSnapAction(model: SnapRenderState): boolean {
   const actions = model.actions;
   if (!isRecord(actions)) return false;