# Placeholders System

## Overview

Placeholders are dynamic tokens embedded in prompt text that get replaced with real data at runtime (email content, headers, user input, etc.).

**Format:** `{%placeholder_id%}`

Example in a prompt: `"Summarize this email: {%mail_text_body_or_selected%}"`

## Placeholder Properties

| Property | Type | Description |
|----------|------|-------------|
| `id` | string | Unique identifier used in `{%id%}` tokens |
| `name` | string | Display name (i18n `__MSG_key__` or plain text) |
| `default_value` | string | Value used if placeholder cannot be resolved |
| `type` | number | `0` = always, `1` = reading only, `2` = composing only |
| `is_default` | string | `"1"` = built-in (not editable/deletable), `"0"` = custom |
| `is_dynamic` | string | `"0"` = fixed value, `"1"` = dynamic (takes a parameter after `:`) |
| `enabled` | number | `0` = disabled, `1` = enabled |
| `text` | string | Content for custom placeholders only |

## Built-in Placeholders (defined in `js/mzta-placeholders.js`)

| ID | Description | Type |
|----|-------------|------|
| `mail_text_body` | Full plain text of the email | 0 |
| `mail_html_body` | Full HTML of the email | 0 |
| `mail_typed_text` | Text typed so far in compose window | 2 |
| `mail_text_body_or_selected` | Plain text body, or selected text if any | 1 |
| `mail_html_body_or_selected` | HTML body, or selected HTML if any | 1 |
| `mail_selected_text` | Only the selected text | 1 |
| `mail_selected_html` | Only the selected HTML | 1 |
| `mail_subject` | Email subject line | 0 |
| `mail_date` | Email date | 1 |
| `mail_author` | Email sender | 0 |
| `mail_recipients` | Email recipients | 0 |
| `mail_tags` | Current tags on the email | 1 |
| `mail_available_tags` | All available tags in Thunderbird | 1 |
| `identity_name` | Current identity display name | 0 |
| `identity_email` | Current identity email address | 0 |
| `identity_signature` | Current identity signature | 0 |
| `additional_text[id]` | User input field (dynamic, shows input in popup) | 0 |
| `mail_header:name` | Any email header by name (dynamic) | 1 |
| `mail_full_headers` | All mail headers (key: value format, newline-separated) | 1 |

## Dynamic Placeholders

Dynamic placeholders use a colon separator to pass a parameter:

```
{%additional_text:my_field_id%}   →  shows an input field labelled "my_field_id" in the popup
{%mail_header:x-spam-score%}      →  fetches the X-Spam-Score header value
```

The `is_dynamic: "1"` property signals this behavior in the placeholder definition.

## Custom Placeholders

Users can define their own placeholders via `pages/customdataplaceholders/`. Custom placeholders:
- Have `is_default: "0"`
- Have a `text` property containing the replacement value
- Are stored in `browser.storage.local`
- Are merged with default placeholders at runtime before prompt processing

## Placeholder Resolution Order

1. Built-in placeholders are defined in `js/mzta-placeholders.js`
2. Custom placeholders are loaded from storage
3. At runtime, `mzta-background.js` gathers email data (via Thunderbird APIs)
4. Each `{%id%}` token in the prompt string is replaced with the resolved value
5. If a value cannot be resolved, `default_value` is used as fallback

## Adding a New Built-in Placeholder

1. Add the object to the `defaultPlaceholders` array in `js/mzta-placeholders.js`
2. Add the `name` i18n key to `_locales/en/messages.json` as `placeholder_<id>` (or choose a descriptive key)
3. Implement the resolution logic in the relevant section of `mzta-background.js`