Live cart total in a surface

A surface shows the shopper's progress to free shipping, bound to app state that never leaves the device.

Goal

The assistant renders a progress block bound to /host/cart/progress and /host/cart/label. As the cart changes, the block updates without any network traffic.

Pieces

SDK: setHostData whenever the cart changes.
Surface: the model (or a trigger fixture) uses bindings under /host/.
Prompt line (optional): “When you show cart help, include a progress block bound to /host/cart/progress with label /host/cart/label.”

Code

void onCartChanged(Cart cart) {
  final total = cart.total;
  Kletso.instance.setHostData({
    'cart': {
      'progress': (total / 3500).clamp(0.0, 1.0),
      'label': total >= 3500 ? 'Free shipping unlocked' : '₹${3500 - total} away from free shipping',
      'items': cart.items.length,
    },
  });
}

Surface node produced by the agent:

"ship": { "type": "progress", "props": { "value": { "path": "/host/cart/progress" }, "label": { "path": "/host/cart/label" } } }

Verify

Ask for checkout help; the progress bar appears. Add an item from the shop behind the chat; the bar and label update immediately.
Conversations inspector: the surface JSON contains the binding paths, not the values.

Notes

Host data is for display. If the model should reason about the amount, also put it in context (updateContext({'cartValue': total})).
The surface’s own data.host.* acts as a fallback when the app has not published host data yet.