<!-- Extension API v0 — pre-1.0. Interfaces may change without notice until P2 seals the custom-code format. First-party extensions track HEAD. -->

# Kit-trees — `composite: 1` (frozen)

A **kit-tree** is a JSON element tree over the [Element Contract](/reference/kit-contract): the only way extensions, themes, stores and agents add storefront UI without shipping code. It is rendered through the active theme's kit, so it looks native everywhere; it is validated statically (elements, props, bindings, caps) before it can ever render. Anything beyond this language is a P2 sealed section.

## Node

```json
{ "el": "Box", "props": { "surface": "surface-alt", "padding": "m" },
  "children": [ { "el": "Heading", "props": { "level": 3 }, "children": [ { "$bind": "$config.baslik" } ] },
                { "el": "KeyValueList", "each": "$ext.ibans", "as": "hesap",
                  "props": { "rows": [ { "key": { "$bind": "$hesap.banka" }, "value": { "$bind": "$hesap.iban" } } ] } } ] }
```

- `el` — an element name from the contract (required + optional elements); unknown = rejected.
- `props` — the element's props (see the contract table); values are scalars, bindings, arrays or objects of those. Platform-reserved props (`id`, `hook`, `sid`, `type`, `island`) are refused.
- `variants` — section-variant axes; `children` — text, bindings or nodes; `each` + `as` — repeat over a list binding (≤ 50); `if` — `"$x"` / `{ "not": "$x" }` / `{ "eq": ["$x", value] }`; `slot: "blocks"` — where a composite's block instances go.
- caps: ≤ 200 nodes, depth ≤ 6. No HTML in text (use the `markdown` formatter into `Prose`).

## Bindings

| prefix | source |
|---|---|
| `$props.*` | a composite instance's props (the owner's form, from the composite's JSON Schema) |
| `$config.*` | a block fill's per-placement config (`configSchema`) |
| `$ext.*` | the extension's OWN config, only the pointers listed in `exposeConfig` |
| `$data.*` | declared data the platform prefetches: `productList`, `productByHandle`, `collectionList`, `metafields` |
| `$ctx.*` | `storeName`, `payments.{cardEnabled,kapidaEnabled,havaleEnabled,taksitAvailable}`, `route.{path,kind,handle}` |
| `$blocks` | a composite instance's block list (`{ type, props }[]`) |
| `$item` / `$<as>` | the current `each` item |

Formatters on a binding: `money` (kuruş → "1.249,90 TL"), `href` (a bundle link → URL), `media` (a media ref → the kit's image source), `markdown` (→ safe HTML for `Prose`).

## Where trees come from

- **Extensions**: manifest `ui.storefront` — `blocks` (≤ 4, placed in [zones](/reference/storefront-zones)), `sections` (≤ 3 composites in the add-picker, type `<ext>.<key>@1`), `pages` (≤ 3, under `/ek/{slug}`). Validated at registry load (D-T1-TREE) and rendered on every first-party kit in CI (G-EXT-UI).
- **Stores**: `layout.composites` in the bundle, type `c.<name>@1` — authored as JSON by agents / the assistant, offered under "Benim bölümlerim".
- **Themes**: `sections/*.composite.json` in a theme package.