> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bytesell.io/llms.txt
> Use this file to discover all available pages before exploring further.

# The builder

> Editing shells and inline-edit attributes.

Merchants edit a theme in a visual builder: a form panel beside a live preview
of their own store. The theme selects the editing shell and marks which elements
are editable in place.

## Editing shells

Set `builder` in `theme.json`.

<CardGroup cols={2}>
  <Card title="full" icon="sliders">
    Section tree, click-to-select on the canvas, drag to reorder, SEO panel,
    nested block editing. The default.
  </Card>

  <Card title="simple" icon="list">
    One scrolling column of forms. No section tree, no click-to-select, no SEO
    panel. Nested blocks are displayed but not editable.
  </Card>
</CardGroup>

`simple` suits a theme small enough that a section tree adds overhead, such as a
link-in-bio layout consisting of a profile and a list of links.

The value is presentation only. Both shells call the same endpoints with the
same scopes and the same concurrency control, and the server does not read it.
It grants and restricts nothing.

An unrecognised value resolves to `full`, including a typo, a wrong type or an
absent key. Resolving to `full` shows extra controls; resolving to `simple`
would hide them.

## Inline editing

`data-bs-edit` makes an element editable in place on the canvas. Its value is
the settings key written back to.

```slurp theme={null}
<h1 data-bs-edit="heading">${ section.settings.heading }</h1>
<div data-bs-edit="body" data-bs-edit-kind="richtext">
  {html section.settings.body sanitize}
</div>
```

| Attribute            | Meaning                                                  |
| -------------------- | -------------------------------------------------------- |
| `data-bs-edit`       | The settings key this element edits                      |
| `data-bs-edit-kind`  | `text`, `richtext` or `image`. Default `text`.           |
| `data-bs-edit-scope` | Set to `theme` to edit a theme-wide setting              |
| `data-bs-block`      | Marks a hand-drawn block for click-to-select and reorder |

`richtext` makes the element contenteditable and stores HTML. `image` is not
edited inline and opens the field in the panel instead.

<Note>
  `data-bs-section`, `data-bs-section-type`, `data-bs-group` and the wrapper
  around each `{blocks}` child are injected by the platform. Do not write them
  in a template.
</Note>

## Live theme settings

The builder applies theme setting changes to the preview without a reload. For
an accent colour it calls a function the theme defines:

```js theme={null}
window.__bsApplyAccent = (name) => { /* set the CSS variables */ }
```

A theme with an `accent` setting that does not define this has no live preview
for it. The merchant's colour change is not visible until reload.

<Warning>
  Accent CSS custom properties must hold RGB channels, not a hex string:

  ```css theme={null}
  --accent: 99 102 241;   /* correct */
  --accent: #6366f1;      /* every accent/opacity utility breaks */
  ```

  A hex value satisfies plain `rgb(var(--accent))` and produces invalid CSS as
  soon as an opacity modifier is applied. The failure is silent.
</Warning>

## The preview

The preview renders the theme against the merchant's own data, on the store's
origin, in an iframe.

* Drafts render through an uncached path, so preview updates are immediate while
  the live store lags by up to a minute.
* The preview is cross-origin from the builder. Communication across that
  boundary goes through the platform's bridge, not through theme code.