Mutations

The ActionResponse contract: how an api action changes a live page.

An api action's response is a list of mutations plus an optional toast. Mutations are applied in order against the loaded page.

ActionResponsejson

{
  "mutations": [
    { "kind": "replace_widget", "id": "product_1", "widget": {} },
    { "kind": "remove_widget", "id": "product_2" },
    { "kind": "append_sections", "sections": [] },
    { "kind": "prepend_sections", "sections": [] },
    { "kind": "replace_page", "page": {} }
  ],
  "toast": { "message": "Added to favourites" }
}

Field	Type	Description
`replace_widget`	mutation	Swaps the widget with the matching id for the provided full widget. The workhorse of in place updates.
`remove_widget`	mutation	Removes the widget with the matching id from sections, header or footer.
`append_sections`	mutation	Adds sections to the end of the page.
`prepend_sections`	mutation	Adds sections to the front of the page.
`replace_page`	mutation	Replaces the whole page. Equivalent to a silent refresh.

Rules#

Mutations decode lossily: one malformed mutation is dropped and diagnosed, the rest apply.
Unknown kind strings are ignored by old clients, so new mutation kinds are backward safe.
replace_widget requires the incoming widget to carry the full envelope, type and data included.
Widget state for an untouched id survives; a replaced widget starts fresh.