feat(taskflow): pass consumer-owned feedback field for display messages through on handles

taskflow/docs/frontend-guide.md

@@ -128,6 +128,7 @@ The `zoneview` renderer (see [template reference](template-reference.md#the-zone
 - `id` is the section's key in the render config. It is unique within the view.
 - `title` is omitted when the section has none.
 - `handles` lists the buttons legal in the current state; it is omitted when there are none, which means the entry is read-only.
+- A handle's `messages` is present only when the render config declares one, and its JSON value arrives unchanged, though encoding may compact whitespace and escape `<`, `>` and `&`. Its shape is defined by your frontend, not by the renderer: it's the place to say what to tell the user once the command has been dispatched.
 - An empty view is `[]`.
 
 The frontend renders the entries top to bottom, picking a widget by `type`.

taskflow/docs/template-reference.md

@@ -230,7 +230,7 @@ The interface (`Renderer.Render(context.Context, json.RawMessage, Facts) (json.R
 }
 ```
 
-- **`sections`** — what can be shown. `visibleWhen` decides whether a section is visible for the current state, data and claims; `handles` are the buttons it offers.
+- **`sections`** — what can be shown. `visibleWhen` decides whether a section is visible for the current state, data and claims; `handles` are the buttons it offers. A handle has a `command`, a `label`, an optional `element` owned by the section's renderer, and an optional `messages`: the feedback the consumer shows once the command has been dispatched. `messages` is passed through to the view as the same JSON value, though encoding may compact whitespace and escape `<`, `>` and `&`.
 - **`layouts`** — named orderings. Each is a permutation of **all** section keys and expresses relative order only, never visibility. States that agree on the relative order of the sections they show can share one layout.
 - **`states`** — per state, `actions` lists the commands legal in it (a section's handle is sent only if its command is listed), and `order` references the layout to render in. The reference must have the form `#/layouts/<name>` and name a defined layout, or rendering fails.
 

taskflow/renderer/zoneview/renderer_test.go

@@ -189,6 +189,42 @@ func TestRender_CarriesTitleAndLegalHandles(t *testing.T) {
 	}
 }
 
+// A legal handle carries its messages through, whatever
+// their shape, and a handle that declares none emits no "messages" key.
+func TestRender_PassesHandleMessagesThrough(t *testing.T) {
+	r := newTestRenderer(t)
+	const config = `{
+	  "id": "test:render",
+	  "sections": {
+	    "user_form": {
+	      "templateId": "t", "title": "User Form", "projector": "MARKDOWN",
+	      "handles": [
+	        { "command": "save_as_draft", "label": "Save as Draft" },
+	        { "command": "submit", "label": "Submit",
+	          "messages": { "QUEUED_EXTERNALLY": { "text": "Sent for review.", "variant": "success" } } }
+	      ]
+	    }
+	  },
+	  "states": {
+	    "PENDING_USER": { "actions": [{ "command": "save_as_draft" }, { "command": "submit" }] }
+	  }
+	}`
+
+	view := decodeView(t, render(t, r, config, tfrenderer.Facts{State: "PENDING_USER"}))
+	if len(view) != 1 {
+		t.Fatalf("got %d components %v, want 1", len(view), view)
+	}
+	got, err := json.Marshal(view[0].Handles)
+	if err != nil {
+		t.Fatalf("marshal handles: %v", err)
+	}
+	const want = `[{"command":"save_as_draft","label":"Save as Draft"},` +
+		`{"command":"submit","label":"Submit","messages":{"QUEUED_EXTERNALLY":{"text":"Sent for review.","variant":"success"}}}]`
+	if string(got) != want {
+		t.Errorf("got handles %s, want %s", got, want)
+	}
+}
+
 // With no render config there is nothing to show: an empty list
 func TestRender_EmptyConfigReturnsEmptyList(t *testing.T) {
 	r := newTestRenderer(t)

taskflow/renderer/zoneview/zoneview.go

@@ -20,15 +20,18 @@ type Action struct {
 // screen element. Command joins this claim to a state-level Action; Label is
 // the user-facing text; Element is a free-form identifier owned by the
 // section's renderer (e.g. "primary_action", "secondary_action" for a FORM
-// projector) — the data layer does not interpret it.
+// projector) — the data layer does not interpret it. Messages is the feedback
+// the consumer shows once the command has been dispatched; its shape is owned
+// by the consumer and it is passed through uninterpreted.
 //
 // "Claim" here means a section laying claim to a command. It is unrelated to
 // the authorization claims in renderer.Facts.Claims, which decide whether a
 // section is rendered at all.
 type HandleClaim struct {
-	Command string `json:"command"`
-	Label   string `json:"label"`
-	Element string `json:"element,omitempty"`
+	Command  string          `json:"command"`
+	Label    string          `json:"label"`
+	Element  string          `json:"element,omitempty"`
+	Messages json.RawMessage `json:"messages,omitempty"`
 }
 
 // SectionView is the per-zone trader-app metadata read from render.json