# Theme code (/ai/reference/storefront/storefront-code)

Toolset `storefront_code`, 16 tools.

## Actions [#actions]

### `resolve_update_conflict` [#resolve_update_conflict]

The 'Let Klea combine them' choice for a theme update: a code file the merchant and the update both changed gets one combined version. Without content it lists the files and reads one: its text with the merchant's lines, the version before the update and the update's lines between marker lines. With content it checks the whole file you resolved it to by the theme builder's type check and bundle, builds a preview of the theme with it, and keeps it as a proposal. It never changes the update: the merchant looks at the preview on the review page and accepts or turns it down.

Read first: call with theme_id and update_id for the list, then with path (and from/to lines when next is set) for one conflict. Resolve by writing the file as it should be after the update: no marker lines, the merchant's changes kept, the update's changes taken. A proposal with errors is not kept; fix them and send it again. Tell the merchant in plain words what the combined version keeps and takes, and that a preview is on the review page; never show them code or marker lines. Does not publish and does not write to the update.

- Action key: `resolve_update.conflict`
- Permission: `theme.read`
- Approval: Runs without approval.
- Effect: Reads only.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme_id` | string | yes | The theme the update belongs to. at least 1 characters |
| `update_id` | string | yes | The open update, from the update review. at least 1 characters |
| `path` | string |  | The conflict file to read or resolve. 1 to 512 characters |
| `from` | integer |  | First line to read; next of the last read. at least 1 |
| `to` | integer |  | Last line to read. at least 1 |
| `content` | string |  | The whole file as resolved, to propose it. Needs path; omit to read. at most 200000 characters |
| `summary` | string |  | One sentence in the merchant's language on what the resolution keeps and takes. at most 400 characters |

Example input:

```json
{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "update_id": "019bb77a-30fc-73e0-a0e9-4af113113214"
}
```

### `theme_check_run` [#theme_check_run]

Build the theme draft and report its type check and build errors.

Build the current draft and wait for it (up to about a minute): status built or failed, the build error and the type check log. This is the authoritative check of a code change; run it before theme_publish.

- Action key: `theme_check.run`
- Permission: `theme.code.write` and `theme.write`
- Approval: Runs without approval.
- Effect: Changes a draft; nothing goes live until it is published.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme_id` | string |  | Theme ID from theme_list. Omit to read the live theme; writes need a theme that is not live.. at least 1 characters |

Example input:

```json
{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe"
}
```

### `theme_draft_build_get` [#theme_draft_build_get]

Where the theme draft's build stands, with the recent publish builds.

The draft build of a theme (queued, built, failed or skipped; its error and type check log) and the theme's recent publish builds. Every saved file starts a draft build on its own.

- Action key: `theme_draft_build.get`
- Permission: `theme.read`
- Approval: Runs without approval.
- Effect: Reads only.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme_id` | string |  | Theme ID from theme_list. Omit to read the live theme; writes need a theme that is not live.. at least 1 characters |

Example input:

```json
{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe"
}
```

### `theme_email_component_create` [#theme_email_component_create]

Scaffold a new code component for the theme emails in a draft theme.

Create src/emails/components/<Name>.tsx from the email component scaffold in a draft theme; then edit it with theme_file_edit.

- Action key: `theme_email_component.create`
- Permission: `theme.code.write` and `theme.write`
- Approval: Waits for approval when the store requires it for this action.
- Effect: Changes a draft; nothing goes live until it is published.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme_id` | string | yes | A theme that is not live, from theme_list; theme_duplicate makes one from the live theme.. at least 1 characters |
| `name` | string | yes | PascalCase component name |

Example input:

```json
{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "name": "OrderBanner"
}
```

### `theme_file_delete` [#theme_file_delete]

Delete files of a draft theme.

Delete files of a draft theme. Each path names the content_hash you read; a file changed since is refused with a conflict. Platform-managed files (.schemas/**) cannot be deleted.

- Action key: `theme_file.delete`
- Permission: `theme.code.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes a draft; nothing goes live until it is published.
- Destructive: in compact mode it runs with `run_destructive_action`.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme_id` | string | yes | A theme that is not live, from theme_list; theme_duplicate makes one from the live theme.. at least 1 characters |
| `files` | list of object | yes | 1 to 200 items |
| `files[].path` | string | yes | Theme file path, such as src/sections/hero.tsx. 1 to 512 characters |
| `files[].expected_hash` | string | yes | The content_hash theme_file_get or theme_file_list returned for this file. 1 to 128 characters |

Example input:

```json
{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "files": [
    {
      "path": "src/sections/old.tsx",
      "expected_hash": "ab12"
    }
  ]
}
```

### `theme_file_edit` [#theme_file_edit]

Exact text replacements in draft theme files, applied all or nothing.

Replace exact text in files of a draft theme. old_str must occur exactly once (whitespace included) unless replace_all is set; several edits of one file apply in order. All edits apply or none do. expected_hash, when sent, must be the content_hash you read; either way a file changed during the edit is refused with a conflict.

- Action key: `theme_file.edit`
- Permission: `theme.code.write`
- Approval: Waits for approval when the store requires it for this action.
- Effect: Changes a draft; nothing goes live until it is published.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme_id` | string | yes | A theme that is not live, from theme_list; theme_duplicate makes one from the live theme.. at least 1 characters |
| `edits` | list of object | yes | 1 to 50 items |
| `edits[].path` | string | yes | Theme file path, such as src/sections/hero.tsx. 1 to 512 characters |
| `edits[].old_str` | string | yes |  |
| `edits[].new_str` | string | yes |  |
| `edits[].replace_all` | boolean |  |  |
| `edits[].expected_hash` | string |  | The content_hash theme_file_get or theme_file_list returned for this file. 1 to 128 characters |

Example input:

```json
{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "edits": [
    {
      "path": "src/sections/hero.tsx",
      "old_str": "Shop now",
      "new_str": "Browse the sale"
    }
  ]
}
```

### `theme_file_get` [#theme_file_get]

The content and content hash of up to 20 theme files.

Read up to 20 files of a theme draft. Each answer carries content_hash, which every write, edit and delete of that file must send back. from_line and to_line (1-based, inclusive) return part of a file. A long file comes back in part, with next_from_line naming where to read on. Assets answer their stored blob instead of content.

- Action key: `theme_file.get`
- Permission: `theme.read`
- Approval: Runs without approval.
- Effect: Reads only.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme_id` | string |  | Theme ID from theme_list. Omit to read the live theme; writes need a theme that is not live.. at least 1 characters |
| `paths` | list of object | yes | 1 to 20 items |
| `paths[].path` | string | yes | Theme file path, such as src/sections/hero.tsx. 1 to 512 characters |
| `paths[].from_line` | integer |  | at least 1 |
| `paths[].to_line` | integer |  | at least 1 |

Example input:

```json
{
  "paths": [
    {
      "path": "src/sections/hero.tsx"
    }
  ]
}
```

### `theme_file_list` [#theme_file_list]

The theme's file index: path, kind, size and content hash.

List the files of a theme draft with their content_hash, 80 per page (next_offset reads on). kind is code (src/**, og/**), manifest (theme.json), asset (assets/**) or content (pages, layout, settings, texts, emails, saved JSON). Filter by prefix, kind or a glob such as src/sections/**/*.tsx.

- Action key: `theme_file.list`
- Permission: `theme.read`
- Approval: Runs without approval.
- Effect: Reads only.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme_id` | string |  | Theme ID from theme_list. Omit to read the live theme; writes need a theme that is not live.. at least 1 characters |
| `prefix` | string |  | at most 512 characters |
| `kind` | string |  | one of "code", "manifest", "asset", "content" |
| `glob` | string |  | at most 512 characters |
| `offset` | integer |  | Files to skip; next_offset of the last page. at least 0 |

Example input:

```json
{
  "prefix": "src/sections/"
}
```

### `theme_file_move` [#theme_file_move]

Rename files of a draft theme.

Rename files of a draft theme. Each move names the content_hash you read; the new path must not exist. Imports of the moved file are not rewritten; search for them with theme_file_search.

- Action key: `theme_file.move`
- Permission: `theme.code.write`
- Approval: Waits for approval when the store requires it for this action.
- Effect: Changes a draft; nothing goes live until it is published.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme_id` | string | yes | A theme that is not live, from theme_list; theme_duplicate makes one from the live theme.. at least 1 characters |
| `moves` | list of object | yes | 1 to 50 items |
| `moves[].from` | string | yes | Theme file path, such as src/sections/hero.tsx. 1 to 512 characters |
| `moves[].to` | string | yes | Theme file path, such as src/sections/hero.tsx. 1 to 512 characters |
| `moves[].expected_hash` | string | yes | The content_hash theme_file_get or theme_file_list returned for this file. 1 to 128 characters |

Example input:

```json
{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "moves": [
    {
      "from": "src/sections/old.tsx",
      "to": "src/sections/new.tsx",
      "expected_hash": "ab12"
    }
  ]
}
```

### `theme_file_patch` [#theme_file_patch]

Apply a unified diff to draft theme files, all or nothing.

Apply a unified diff (--- a/path, +++ b/path, @@ hunks; --- /dev/null creates a file) to a draft theme. Each hunk must match the file at its line or at exactly one place. All files apply or none do; a file changed during the patch is refused with a conflict. Delete files with theme_file_delete.

- Action key: `theme_file.patch`
- Permission: `theme.code.write`
- Approval: Waits for approval when the store requires it for this action.
- Effect: Changes a draft; nothing goes live until it is published.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme_id` | string | yes | A theme that is not live, from theme_list; theme_duplicate makes one from the live theme.. at least 1 characters |
| `patch` | string | yes | 1 to 500000 characters |

Example input:

```json
{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "patch": "--- a/src/sections/hero.tsx\n+++ b/src/sections/hero.tsx\n@@ -1,1 +1,1 @@\n-Shop now\n+Browse the sale\n"
}
```

### `theme_file_search` [#theme_file_search]

Literal or regular expression search across the text files of a theme.

Search the text files of a theme draft. Answers path, line and the line text, at most 200 matches.

- Action key: `theme_file.search`
- Permission: `theme.read`
- Approval: Runs without approval.
- Effect: Reads only.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme_id` | string |  | Theme ID from theme_list. Omit to read the live theme; writes need a theme that is not live.. at least 1 characters |
| `query` | string | yes | 1 to 500 characters |
| `regex` | boolean |  | Treat query as a JavaScript regular expression |
| `case_sensitive` | boolean |  |  |
| `prefix` | string |  | at most 512 characters |

Example input:

```json
{
  "query": "useCart"
}
```

### `theme_file_write` [#theme_file_write]

Create or replace up to 50 whole files in a draft theme.

Write whole files to a draft theme, never the live one. Every file carries expected_hash: the content_hash you read, or null to create a new file. A file changed since you read it is refused with a conflict and nothing is written; read it again and redo the change. A dry run checks paths, imports, page layouts and hashes without writing. For a small change prefer theme_file_edit.

- Action key: `theme_file.write`
- Permission: `theme.code.write`
- Approval: Waits for approval when the store requires it for this action.
- Effect: Changes a draft; nothing goes live until it is published.
- Retries: safe to repeat with the same input.
- Dry run: supported, with `dry_run` set to true.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme_id` | string | yes | A theme that is not live, from theme_list; theme_duplicate makes one from the live theme.. at least 1 characters |
| `files` | list of object | yes | 1 to 50 items |
| `files[].path` | string | yes | Theme file path, such as src/sections/hero.tsx. 1 to 512 characters |
| `files[].content` | string |  | The whole new file text |
| `files[].content_base64` | string |  | An asset file as base64, instead of content |
| `files[].expected_hash` | string or null | yes | The content_hash you read; null creates the file and fails when it exists. 1 to 128 characters |

Example input:

```json
{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "files": [
    {
      "path": "src/sections/promo.tsx",
      "content": "export ...",
      "expected_hash": null
    }
  ]
}
```

### `theme_preview_capture` [#theme_preview_capture]

Screenshots of a draft page, to check a code change by eye.

Capture a page of the theme draft (desktop by default, or mobile at 390 px). The draft must have finished building; theme_check_run waits for that.

- Action key: `theme_preview.capture`
- Permission: `theme.code.write` and `theme.write`
- Approval: Runs without approval.
- Effect: Changes a draft; nothing goes live until it is published.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme_id` | string |  | Theme ID from theme_list. Omit to read the live theme; writes need a theme that is not live.. at least 1 characters |
| `page_path` | string |  | at most 512 characters |
| `viewport` | string |  | one of "desktop", "mobile" |

Example input:

```json
{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "page_path": "/"
}
```

### `theme_preview_create` [#theme_preview_create]

A preview link of the draft, or of the draft with some files replaced, without saving them.

Without files: a signed preview link of the theme draft once its build is done. With files: a scratch preview of the draft with those files replaced, built on its own and never saved to the draft. Waits up to about a minute for the build.

- Action key: `theme_preview.create`
- Permission: `theme.code.write` and `theme.write`
- Approval: Runs without approval.
- Effect: Changes a draft; nothing goes live until it is published.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme_id` | string |  | Theme ID from theme_list. Omit to read the live theme; writes need a theme that is not live.. at least 1 characters |
| `files` | list of object |  | at most 50 items |
| `files[].path` | string | yes | Theme file path, such as src/sections/hero.tsx. 1 to 512 characters |
| `files[].content` | string | yes |  |
| `page_path` | string |  | Storefront path to open, such as /products/hat. at most 512 characters |

Example input:

```json
{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe"
}
```

### `theme_revision_diff` [#theme_revision_diff]

What changed between the draft, the live theme and any saved version.

Compare two versions of a theme: by default the draft against what shoppers see now. Answers each changed file (added, modified, removed; lines added and removed), whether code changed, and the flagged patterns a publish approval shows. diff adds unified diffs, paths narrows them.

- Action key: `theme_revision.diff`
- Permission: `theme.read`
- Approval: Runs without approval.
- Effect: Reads only.
- Retries: safe to repeat with the same input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme_id` | string |  | Theme ID from theme_list. Omit to read the live theme; writes need a theme that is not live.. at least 1 characters |
| `base` | string |  | draft, live (what shoppers see now) or a revision id from theme_revision_list. 1 to 64 characters |
| `head` | string |  | draft, live (what shoppers see now) or a revision id from theme_revision_list. 1 to 64 characters |
| `diff` | boolean |  |  |
| `paths` | list of string |  | at most 50 items. 1 to 512 characters |

Example input:

```json
{
  "theme_id": "019bb750-d787-7e78-920e-76e98d4de1fe",
  "diff": true
}
```

### `theme_revision_rollback` [#theme_revision_rollback]

Bring an earlier theme version back into the draft.

Restore the draft to a revision from theme_revision_list, replacing every draft theme file, including edits made after it. The live store changes only after theme_publish.

- Action key: `theme_revision.rollback`
- Permission: `theme.write`
- Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Destructive: in compact mode it runs with `run_destructive_action`.
- Retries: runs at most once; a repeat with the same idempotency key returns the first result.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `theme_id` | string |  | Theme ID. Omit to use the store active theme, or the only theme if none is marked active. |
| `revision_id` | string | yes | Revision id to restore. at least 1 characters |

Example input:

```json
{
  "revision_id": "019bb77a-30fc-73e0-a0e9-4af113113214"
}
```