Bounded payloads

--max-base64-bytes puts a ceiling on the visual payload. What makes it usable rather than frustrating is not that it can shrink a response, but the order in which it does so — and that it tells you exactly what it changed.

Fitting is opt-in

With no budget, no fitting runs at all. With a budget that is already satisfied, the plan is returned untouched and the response says so:

{
  "payload": {
    "budget_base64_bytes": 3000000,
    "actual_base64_bytes": 287400,
    "fit": "exact",
    "adjustments": []
  }
}

Adaptation that happens without pressure is a response the caller cannot reproduce. So it never happens.

The reduction order, and why the order matters

Each step is applied repeatedly until it can do no more, and only then does the next step begin. That detail is what makes the order a real protection rather than a formality.

A frame is degraded, never omitted

An earlier design marked older frames’ overviews as optional, so under pressure the fitter dropped them. A request for three frames returned one — and because the frame that came back was whole, the response looked complete.

That is the worst shape of failure: correct-looking and undetectable by the caller. The rule now is that the overview of every requested frame is required. newest-detailed lowers an older frame’s rendering, never its existence.

So ask for four frames and you get four frames, with fewer bytes rather than fewer frames.

Views marked optional may be omitted; required views never are

Required views are never omitted. If the required content cannot fit even at its floors, the request fails with payload_budget_exceeded (exit 26) rather than returning a shortened response.

Optional views drop first. A changed crop, for instance, is required by default — a caller that asked for it asked for a reason — and --changed-optional is how you say it may be dropped.

The error message states the smallest budget that would succeed

A budget that cannot be met does not just fail. It tells you the number to use instead:

{
  "error": {
    "code": "payload_budget_exceeded",
    "message": "payload budget exceeded: the required views cannot fit in a
                budget of 3000 base64 bytes even at their minimum settings;
                the smallest achievable payload is 3304 bytes. Raise the
                budget, lower the floors, or make a view optional."
  }
}

That floor is computed by walking the same ladder the fitter walks, so a budget at exactly that number genuinely succeeds. It is also never reported as higher than what the unfitted request would have cost — a subtlety worth stating, because the most-degraded plan is not always the cheapest one.

Every adjustment is reported as a separate entry

{
  "payload": {
    "budget_base64_bytes": 300000,
    "actual_base64_bytes": 287400,
    "fit": "adjusted",
    "adjustments": [
      { "change": "quality", "frame_id": 2, "view": "overview",
        "requested": 85, "actual": 65 },
      { "change": "omitted", "frame_id": 1, "view": "minimap",
        "reason": "optional view omitted to meet the payload budget" }
    ]
  }
}

A view also carries its own applied settings, so an adjustment is visible in the view itself rather than only in the fit report. Two independent places to look, and they always agree.

The same frames and policy always produce the same plan

Identical raw frames and an identical policy produce an identical plan. The ladder orders views by a single total key — priority, then frame position, then kind, then source rectangle, then name — rather than by the order a hash map happened to yield, so the fitted plan is itself a comparable value rather than something that merely comes out the same.

The budget counts base64 bytes, not encoded bytes

The unit of the budget is base64 bytes, because that is what crosses the wire and what a caller is actually paying for. Budgeting in encoded bytes would under-count by about a third.

Next: turning a bounding box into an image — the changed crop.