# Canonical Response Mapping and Runtime Model

## Ownership

New response mappings are top-level `project.bindings`. The legacy `action.responseMapping` field remains schema-compatible but is not executed and must not be authored by new UI/examples.

```json
{
  "id": "binding_inventory",
  "source": "actions.loadInventory.response.body.items",
  "target": "components.inventoryTable.rows",
  "trigger": "onSuccess"
}
```

## Action execution

Actions are project-level and reusable. A Button `onClick`, Dropdown `onChange` where supported, or page lifecycle event selects an `actionId`. A Button event may instead contain `navigateToPageId`; navigation is not represented as a REST action.

Before execution, request fields interpolate:

- `{{components.<name>.value}}` against components on the invoking page only.
- `{{variables.<name>}}` against global variables or page variables owned by the invoking page.

Credential-backed authentication is resolved by the backend through opaque `secretReferenceId`. Browser clients never supply authoritative URLs, authentication modes, actions, or secret values for published execution.

## Response source paths

Canonical action sources begin with:

```text
actions.<actionId>.response
actions.<actionId>.response.body
actions.<actionId>.response.body.<dot-separated-field>
```

The current resolver supports ordinary dot-separated object traversal. JSONPath filters, wildcards, quoted dotted keys, and transform expressions are deferred.

## Targets

Supported action-response targets are validated against component type/property compatibility:

- `components.<name>.value`
- `components.<dropdownName>.options`
- `components.<tableName>.rows`
- `variables.<name>`

Component names are page-local. Response bindings execute in the invoking page context and may update components on that page, global variables, and page variables owned by that page. Cross-page component/page-variable writes are prohibited.

## Triggers

- `onSuccess` is the canonical trigger for an action response and runs only when `ProxyResponse.ok` is true.
- Legacy action-response `onClick` is accepted for compatibility and should be migrated to `onSuccess`.
- Table `components.<name>.selectedRow` bindings use `onChange`.
- `onError`, action chaining, and arbitrary reactive component graphs are deferred.

## Runtime state

Configured defaults remain in canonical project JSON. Preview/published component, action, and variable values live in ephemeral runtime state and never mutate the canonical document. Global and page values survive in-session page navigation and reset on full reload.

Actions expose loading, success, upstream failure, network/policy failure, and mapping failure states. Mapped components receive loading/error state while requests run. When a successful action has no mapping, the triggering control surfaces the response for operator feedback.

## Lifecycle

- Page `onLoad` runs on the first entry to that page during one loaded runtime session.
- Page `onEnter` runs when returning to a previously visited page.
- Reopening/reloading the runtime begins a fresh session.

## Diagnostics

Validation rejects or warns about:

- dangling action, binding, page, component, variable, and secret references;
- unsupported trigger/source/target combinations;
- duplicate page/component identities in their required scopes;
- malformed templates and unsupported component template properties;
- page-variable ownership violations and cross-page references;
- incompatible response target properties;
- deprecated `action.responseMapping` and inert `inputMap` compatibility fields.

The backend performs schema and semantic validation before persistence/publication. The frontend shows the same actionable paths without replacing the last valid project state.