best-email-builder 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,196 @@ All notable changes are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
 [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [0.5.0] — 2026-10-15
+
+### Changed — the AI is a module (breaking)
+- Everything AI moved to its own entries: `best-email-builder/ai` (the
+  builder's side) and `best-email-builder/ai/server` (the generator, the
+  prompts, `claudeEmailModel`). An application that does not import them has
+  no AI button anywhere, and none of the AI's code or texts in its bundle.
+- The builder takes the module as a prop: `<EmailBuilder ai={createAi()} />`
+  (`EmailStudio` passes it on). `createAi()` calls the handler's routes;
+  `createAi({ baseUrl, headers })` other ones; `generate`, `rewrite` and
+  `suggestSubjects` can each be `false` (no button) or a function of your own.
+- Removed: `createHttpStorage({ generate: true })` and the storage's
+  `generate`, `rewrite` and `suggestSubjects`; `createEmailGenerator`,
+  `claudeEmailModel` and the prompts are no longer exported by
+  `best-email-builder/server` — import them from `best-email-builder/ai/server`.
+  The handler still takes the generator as `generator`.
+
+### Added
+- **AI providers by their key**, nothing to install: `providerEmailModel({ provider, apiKey })`
+  and `createAi({ provider, … })` for OpenRouter (default `openrouter/free`,
+  free models), Google Gemini, Groq, Cerebras, Mistral, OpenAI, DeepSeek,
+  Ollama and any OpenAI-compatible API (`{ baseUrl, model }`). Structured
+  output where the model takes it, stepped down to a JSON object, then plain
+  JSON, once. `AI_PROVIDERS` lists them with their default model, where to get
+  a key and what is free. New errors, translated: `KEY_MISSING`,
+  `KEY_REFUSED`, `MODEL_CREDITS`, `MODEL_BUSY`, `MODEL_ERROR`.
+- **Each user's own key**: `createAi({ provider, askKey: true })` (off by
+  default) — the first AI action opens a *Connect* dialog (the provider, a
+  link to get a key, what is free, the key hidden or shown), the key is kept
+  in that browser and sent only to the provider; a refused key is forgotten
+  and asked again in the same action. `ai.key` reads and changes it.
+- **Ctrl K** (⌘K on Apple) puts the cursor in the search of *Generate* and of
+  the variables menu, as in the template library; each search shows the hint.
+- The live demo runs the AI with the visitor's own OpenRouter key, asked in
+  the *Connect* dialog instead of the browser's prompt; its code samples have
+  a *With AI* tab.
+
+### Fixed
+- Dark-mode preview: text and lines are now decided against the background
+  they really sit on (nested tables, `bgcolor`, CSS), by contrast; legacy
+  attributes (`<font color>`, `<body text link>`, `bgcolor` without `#`),
+  `hsl()` colors and per-rule CSS are handled; comments, Outlook-only blocks
+  and the doctype are left alone; the dark sheet goes in the real `<head>`.
+- *Suggest subjects*: a subject quoting itself, a list introduced by a line of
+  prose, entities in the email's words, a merge tag of another tool
+  (`*|FNAME|*`, `%name%`), more than 90 characters, capitals the email does not
+  use, "!!" or the preheader repeated are no longer offered; the language
+  falls back to the server's. In the list, what the user types becomes
+  "yours", another email loaded closes it, "More ideas" avoids every idea
+  already shown and keeps the chosen one, the arrows move through it, and a
+  cancelled request can no longer end the one after it.
+- MJML a model escaped twice (`\"`, `\n` left in the markup — some free
+  models do) is read as MJML instead of failing the draft or the rewrite.
+- Types: `createEmailGenerator()`'s `rewrite` and `suggestSubjects` named
+  input types the declaration file did not import (a TypeScript error without
+  `skipLibCheck`).
+
+## [0.4.0] — 2026-10-15
+
+### Changed — the builder's own engine (breaking)
+- **GrapesJS is gone.** The interface, the canvas, the drag and drop and the
+  text editing are the builder's own (`src/engine/`); the email is a tree of
+  MJML elements, and MJML alone turns it into HTML. The canvas shows the email
+  compiled by `mjml-browser` 5.4.1 (the same MJML version as the server): what
+  is seen is what is sent. The package lost GrapesJS and grapesjs-mjml from its
+  dependencies, and its stylesheet their CSS.
+- Stored documents are written by the engine `beb-mjml` (project: the MJML
+  tree). **Templates saved before** (engine `grapesjs-mjml`) open from their
+  stored MJML, versions included, and are saved in the new format next time;
+  a local draft of the old format is dropped.
+- `editor.exportHtml()` returns a Promise (MJML 5 compiles asynchronously).
+- `createGrapesJsAdapter` is replaced by `createNativeAdapter`; `parseMjml`,
+  `parseMjmlFragment` and `serializeMjml` are exported.
+- `createEmailEditor({ …, t })` takes the interface's translator: the texts a
+  block brings and the names in the canvas follow the language. A block's
+  `mjml` / `sectionMjml` may be a function of `t`.
+
+### Added
+- **Generate an email with AI.** A *Generate* button opens a dialog with 68
+  purposes as badges in 8 groups (sales, holidays, events, news, account,
+  orders, relationship, organization), a search field and an optional line of
+  details. The email is written in the interface's language with the
+  builder's sender and variables, cleaned for the builder (longhand padding,
+  sections and columns only, no stock photos, unknown variables as visible
+  placeholders), validated like a saved template, and opens in the editor with
+  its subject and preview text. Server: `createEmailGenerator({ model })`,
+  `claudeEmailModel({ client })` (Claude Opus 5.5, structured output,
+  streamed), the `generator` option of the handler (`POST /generate`, 30 per
+  user per hour); client: `createHttpStorage({ generate: true })`. Any other
+  provider plugs in as a function. The live demo generates with the visitor's
+  own Anthropic key.
+- **Rewrite with AI.** Selecting a text or a button shows, in its properties,
+  *Shorter*, *Longer*, *Fix mistakes*, *Friendlier*, *More formal*,
+  *Translate* (13 languages) and a field to say what to change. The text is
+  replaced in place, in one step of the history (Ctrl+Z). Links and variables
+  must survive and the HTML must pass the validator, or the model gets one more
+  turn and then nothing changes; a button label stays plain text. Server:
+  `generator.rewrite` (`createEmailGenerator` returns it), `POST /rewrite`
+  (200 per user per hour, `rateLimits.rewritePerHour`), `claudeEmailModel`'s
+  `rewriteEffort` (`'low'`); client: `storage.rewrite`, given by
+  `createHttpStorage({ generate: true })`. `editor.getElement(id).html` returns
+  the stored HTML of a text block.
+- **Your brand.** A *Brand* button opens one dialog: the company's website
+  first (*Get my brand* reads its logo, main color, headings color, font and
+  name), then every field by hand, with a live preview. Saving keeps the
+  brand for the workspace and repaints the email being edited in one step
+  (Ctrl+Z); new emails, gallery templates, inserted blocks and generated
+  emails start in it. Emails are repainted by role (filled buttons and
+  colored banners, bold headings, colored links, fonts; gray footers and body
+  text kept), and the text on a colored background switches to what reads.
+  Server: `brandStore` (`createMemoryBrandRepository`), `brandImporter`
+  (`createBrandImporter`: public http(s) addresses on ports 80/443 only,
+  private, link-local, metadata and IPv4-in-IPv6 addresses refused at the
+  DNS lookup and on every redirect, size and time limits), routes
+  `GET/PUT /brand` and `POST /brand/import` (20 per user per hour,
+  `rateLimits.brandImportsPerHour`); client: `createHttpStorage({ brand: true })`,
+  `storage.loadBrand / saveBrand / importBrand`. `applyBrand`, `cleanBrand`,
+  `brandedSender`, `isPublicAddress`, `editor.setBrand` and `editor.setMjml`
+  (replace the email in one undoable step) are exported. The live demo keeps
+  the brand in `localStorage`.
+- **Suggest subjects.** Under the subject, one click gives three other
+  subject lines drawn from the words of the email, each from its own angle.
+  They are a list to pick from, the user's own subject first to come back to;
+  *More ideas* asks for three new ones. Plain lines, distinct, in the email's
+  language, merge tags only from the catalog (one repair turn, fewer than
+  three still shown). Server: `generator.suggestSubjects`, `POST /subjects`
+  (100 per user per hour, `rateLimits.subjectsPerHour`); client:
+  `storage.suggestSubjects`, given by `createHttpStorage({ generate: true })`.
+  `emailWords` and `SUBJECTS_SYSTEM_PROMPT` are exported.
+- **Dark mode in the preview.** A sun / moon switch next to Desktop / Mobile
+  shows the email as the apps that repaint it in dark mode do (Gmail and
+  Outlook apps, Outlook.com): light backgrounds and borders turn dark of the
+  same hue, dark text turns light, brand colors, light text and images stay —
+  a dark logo on a transparent background disappears there as it does in
+  those apps. Simulated on the compiled HTML, without script: the frame stays
+  sandboxed. In the editor's preview and in the template library.
+  `simulateDarkMode(html)` is exported.
+- Drag and drop with pointer events: a line shows where the block lands
+  (between two elements of a column, or between two sections — a content block
+  then gets a section of its own), the canvas scrolls near its edges, Esc
+  cancels. Sections and elements move by the ✥ handle of their toolbar.
+- On the selection: its name, and a toolbar — select the parent, move,
+  duplicate, delete. Keyboard: Delete, Ctrl+Z / Ctrl+Y, Ctrl+C / Ctrl+V,
+  Ctrl+D, Escape (parent), Enter (edit the text).
+- Ctrl+A selects every block of the email (each section outlined, "All
+  blocks" in the panel); Delete — or the panel's delete button — removes them
+  in one step, Ctrl+Z brings them back. Inside a text being edited or a field,
+  Ctrl+A keeps selecting the text. `editor.selectAll()` does the same.
+- The toolbar's first button names where it goes ("⤴ Column", "⤴ 2 columns"):
+  it selects the parent element; a bare up arrow read as "move up".
+- Panel features for well-made emails: **column widths** (1/4 to 3/4; the
+  other columns of the section share the rest, "Equal" resets), a section
+  **background across the whole screen**, an image **full width on mobile**,
+  menu links **as typed or in capitals** (MJML capitalised them; new menus
+  are written as typed).
+- The server's HTML gets `x-apple-disable-message-reformatting` and
+  `format-detection` (Apple Mail does not rescale the email, iOS does not turn
+  dates, addresses and phone numbers into blue links).
+- Email-client checks on the compiled HTML of every template and of an email
+  holding every block (tests/unit/email-clients.test.mjs): Outlook's MSO
+  tables and VML backgrounds, Gmail's 102 KB clipping and dropped CSS, images
+  (alt, width, no border), mobile media queries and the fallback without
+  `<style>`, links, and the same body from the canvas compiler and the
+  server's. And rendered in a browser at 640 px, 375 px and without `<style>`
+  (e2e/rendering.stories.spec.js).
+- The template library is called a library everywhere ("Bibliothèque de
+  modèles e-mail" in French, instead of "Banque").
+- Text edited in place (double-click, or a click on a selected text) with a
+  formatting bar: bold, italic, underline, strike, link, unlink, clear. Pasted
+  content arrives as plain text, Enter is a line break, the HTML is reduced to
+  what an email accepts.
+- The panel shows MJML's own default in an empty field (a section's padding:
+  20 px above and below) and keeps it for the sides not edited.
+- New layouts start with empty columns showing "Drop a block here" (canvas
+  only); an image without file shows a frame sized to its column.
+
+### Fixed
+- Dropping an image opened an empty "Select an image" dialog of the old engine.
+- A 2-column layout was named "Section" in the canvas and the panel; it is now
+  "2 columns", and every element carries its block's name, in both languages.
+- Blocks inserted English texts ("Your text.", "Column 1", "Learn more"…) in a
+  French interface; their texts now follow the interface's language.
+- An empty padding showed 0 while MJML renders 20 px (sections) or 10 px
+  (texts, top and bottom); editing one side set the others to 0.
+- The button's "Label" field was not translated.
+- The server-side project check now also reads the new project's `tag` field
+  (an `mj-raw` or `script` element in a tampered project is refused).
+
 ## [0.3.0] — 2026-10-13
 
 ### Added

package/README.md

@@ -21,8 +21,9 @@ canvas you have to wire to MJML, storage, validation and sending yourself.
 Best Email Builder is the second option done once, properly, and given away:
 
 - **Free and MIT-licensed** — use it in commercial products, fork it, ship it.
-- **No account, no API key, no vendor.** It is a React component and a server
-  handler you run in your own app, against your own database.
+- **No account, no vendor.** It is a React component and a server handler
+  you run in your own app, against your own database. The AI generation is
+  optional and runs on your server, with your own key.
 - **Readable from end to end.** The engine is hidden behind one adapter, every
   block and feature is a registry entry, and the rules a template must obey
   live in one validation folder — so it is easy to change what you need.
@@ -31,24 +32,58 @@ Best Email Builder is the second option done once, properly, and given away:
   oddly are all welcome — see [Contributing](#contributing).
 
 - **MJML under the hood** — every block compiles to battle-tested, table-based
-  email HTML. You never write a `<table>` by hand.
+  email HTML. You never write a `<table>` by hand. Every template is checked
+  against what Outlook (MSO tables, VML backgrounds), Gmail (102 KB clipping,
+  dropped CSS) and Apple Mail need, and rendered at desktop and phone widths
+  in the test suite.
 - **The blocks emails are made of**: heading, text, image, button, divider,
   spacer, social links, menu, 1 to 4 columns, image + text, and a hero banner
   with a background image — sections take a background image too.
-- **Your UI, your storage, your rendering.** The builder is a React component
-  with its own interface; GrapesJS is only the internal canvas engine, hidden
-  behind an adapter. Templates are stored by *your* backend, as a versioned JSON
-  project (the source of truth) plus server-compiled HTML.
+  Columns take a share of the row (1/4 to 3/4), a section's background can
+  span the whole screen, an image can take the full width on phones.
+- **Its own editor, end to end.** The interface, the canvas and the drag and
+  drop are the builder's own; the email is a tree of MJML elements, and MJML
+  alone turns it into HTML. The canvas shows the real compiled email — what you
+  see is what Outlook, Gmail and Apple Mail receive. Templates are stored by
+  *your* backend, as a versioned JSON project (the source of truth) plus
+  server-compiled HTML.
+- **Editing that behaves**: drag a block, a line shows exactly where it will
+  land; double-click a text to type in place, with bold, italic, underline,
+  links; every element has its name, its toolbar (parent, move, duplicate,
+  delete) and its keyboard shortcuts; an empty field of the panel shows the
+  value MJML will really use.
 - **Server-side rendering only.** The browser never sends HTML: the server
   validates the project and the MJML, compiles, and stores its own HTML.
+- **An email written from scratch by AI** — the user picks what it is for
+  among 68 purposes (sale, Christmas, password reset, meeting reminder, order
+  shipped…), adds a line of details if they want, and a complete email opens in
+  the editor, subject and preview text included, ready to edit and save. The
+  model's MJML is cleaned and checked like any template before it gets there.
+  OpenRouter, Gemini, Groq, Mistral, OpenAI, DeepSeek, Cerebras, Ollama or any
+  OpenAI-compatible API by its key — free tiers included — and Claude through
+  its SDK; on your server, or in the page with each user's own key.
+- **Any text rewritten in one click** — select a text or a button: *Shorter*,
+  *Longer*, *Fix mistakes*, *Friendlier*, *More formal*, *Translate* into 13
+  languages, or say what to change in your own words. The text changes in
+  place, links and variables kept; Ctrl+Z brings the previous one back.
+- **Three subject lines on demand** — drawn from the words of the email, each
+  from its own angle; a click puts one in the subject, your own stays in the
+  list to come back to.
+- **The AI is optional** — a module of its own (`best-email-builder/ai`):
+  without it, no AI button, and none of its code in your bundle.
+- **Your brand in every email** — give your website: the logo, colors and
+  font are read from it (or set by hand), and new emails, templates and
+  blocks start in them.
 - **A gallery of ready-made emails** — newsletter, welcome, promotion, event
   invitation… each one with the sender's footer and the unsubscribe link, so
   nobody starts from a blank page or forgets the legal mentions.
 - **Production features**: undo/redo, desktop/mobile canvas, autosave and local
   drafts, versions, conflict detection between concurrent editors, image
   uploads, server preview with quality checks (missing alt text, missing
-  unsubscribe link, unknown variables, Gmail clipping…), test sends.
-- **Merge-tag variables your users create themselves** — searchable menu,
+  unsubscribe link, unknown variables, Gmail clipping…) and a dark-mode view
+  (as the Gmail and Outlook apps repaint emails), test sends.
+- **Merge-tag variables your users create themselves** — searchable menu
+  (Ctrl K, like every search of the builder),
   insertion at the caret, in the subject line too, sample values for the
   preview and fallbacks for recipients without a value.
 - **Framework-agnostic server**: one Fetch-API handler for Next.js, Hono, Bun,
@@ -56,9 +91,10 @@ Best Email Builder is the second option done once, properly, and given away:
 - **English and French** built in, any other language through a dictionary.
 
 ```
-React UI ─► EmailEditor ─► GrapesJsAdapter ─► GrapesJS + grapesjs-mjml
- (ui/)        (core/)        (adapters/)          internal engine
-                                                         │ project JSON + MJML
+React UI ─► EmailEditor ─► NativeAdapter ─► the email: an MJML tree
+ (ui/)        (core/)        (engine/)        │  canvas = the email compiled
+                                              │  by mjml-browser
+                                              │ project JSON + MJML
 Server: validation ─► MJML compilation ─► variables ─► links ─► final HTML
 ```
 
@@ -110,9 +146,9 @@ and each has its own entry point, so one never brings the other's code:
 
 | Block | Import | What it is |
 |---|---|---|
-| A — the bank | `import { TemplateLibrary } from 'best-email-builder/library'` | Your templates and the ready-made bases in a searchable list, the selected one's details, its rendered preview (desktop / mobile). *Edit*, *New template* and *Start from this base* only call `onEdit(template)` / `onCreate(start)` — it never mounts an editor, and does not load GrapesJS. |
-| B — the editor | `import { EmailBuilder } from 'best-email-builder/builder'` | The editor (above). Opens whatever the host hands it; knows nothing of the bank. |
-| A + B | `import { EmailStudio } from 'best-email-builder'` | The two wired together: the bank, then the editor, then back to the bank with the template just saved selected. The editor has no *Templates* button there — the bases are in the bank. |
+| A — the library | `import { TemplateLibrary } from 'best-email-builder/library'` | Your templates and the ready-made bases in a searchable list, the selected one's details, its rendered preview (desktop / mobile, light / dark). *Edit*, *New template* and *Start from this base* only call `onEdit(template)` / `onCreate(start)` — it never mounts an editor, and loads neither the editor's engine nor its MJML compiler. |
+| B — the editor | `import { EmailBuilder } from 'best-email-builder/builder'` | The editor (above). Opens whatever the host hands it; knows nothing of the library. |
+| A + B | `import { EmailStudio } from 'best-email-builder'` | The two wired together: the library, then the editor, then back to the library with the template just saved selected. The editor has no *Templates* button there — the bases are in the library. |
 
 `best-email-builder` (the main entry) still exports everything; the two
 sub-entries are for an application that wants one block only. Both use the
@@ -126,12 +162,12 @@ import { EmailStudio, createHttpStorage } from 'best-email-builder';
 <EmailStudio storage={createHttpStorage()} locale="fr" sender={sender} />
 ```
 
-#### Block B with your own bank
+#### Block B with your own library
 
-Your bank (a table, a sidebar, a modal — anything) only decides what the
+Your library (a table, a sidebar, a modal — anything) only decides what the
 editor opens, and hears back when it saves or closes:
 
-| Your bank wants to… | Pass to `EmailBuilder` |
+| Your library wants to… | Pass to `EmailBuilder` |
 |---|---|
 | open a saved template | `templateId={id}` (the editor loads it from `storage`) |
 | start from content it has (a base, an import, a copy) | `initialMjml={mjml}` and, optionally, `initialMeta={{ subject, preheader }}` |
@@ -150,7 +186,7 @@ import { EmailBuilder, createHttpStorage } from 'best-email-builder/builder';
 const storage = createHttpStorage();
 
 function Emails() {
-  const [open, setOpen] = useState(null); // null = my bank
+  const [open, setOpen] = useState(null); // null = my library
 
   if (!open) {
     return (
@@ -267,6 +303,222 @@ const subject = applyVariablesToText(template.subject, values, variables);
 With an email provider that does its own merge, map the tags instead:
 `mapVariables(html, { 'contact.firstname': '{{ contact.FIRSTNAME }}' })`.
 
+### 4. AI (an optional module)
+
+The AI is a module of its own, `best-email-builder/ai`. An application that
+does not import it has no AI button anywhere, and none of the AI's code or
+texts in its bundle. Given to the builder, it brings three things:
+
+- **Generate** (toolbar) — asks one thing: what the email is for (a badge
+  among 68, grouped: sales, holidays, events, news, account, orders,
+  relationship, organization), with an optional line of details. The email is
+  written in the interface's language, with the builder's sender and
+  variables, and replaces the one being edited — the dialog says so before,
+  not after.
+- **Rewrite with AI** (properties of a text or a button) and **Suggest
+  subjects** (under the subject), below.
+
+```jsx
+import { createAi } from 'best-email-builder/ai';
+
+<EmailBuilder storage={storage} ai={createAi(/* where the model runs, below */)} />
+```
+
+Pass `generate: false`, `rewrite: false` or `suggestSubjects: false` to leave
+a part out (its button with it), or functions of your own for any of them.
+
+#### Where the model runs
+
+**On your server** — the key stays there; the right choice for production:
+
+```js
+// server
+import { createEmailBuilderHandler, compileMjml } from 'best-email-builder/server';
+import { createEmailGenerator, providerEmailModel } from 'best-email-builder/ai/server';
+
+const handler = createEmailBuilderHandler({
+  /* … */
+  generator: createEmailGenerator({
+    model: providerEmailModel({ provider: 'openrouter', apiKey: process.env.OPENROUTER_API_KEY }),
+    compile: compileMjml, // MJML's own warnings go back to the model
+  }),
+  rateLimits: { generatePerHour: 30, rewritePerHour: 200, subjectsPerHour: 100 }, // per user (defaults)
+});
+```
+
+```jsx
+// browser: the handler's /generate, /rewrite and /subjects routes
+<EmailBuilder storage={createHttpStorage()} ai={createAi()} />
+```
+
+`createAi({ baseUrl, headers })` points at the same routes elsewhere, or with
+the user's credentials. Without a `generator`, those routes answer 501.
+
+**In the page, with each user's own key** — no server needed: the first AI
+action opens a *Connect* dialog (the provider, a link to get a key, what is
+free), the key is kept in that browser and sent only to the provider. A key
+the provider refuses is forgotten and asked again. Off by default:
+
+```jsx
+const ai = createAi({ provider: 'openrouter', askKey: true });
+```
+
+`ai.key` reads and changes it: `get()`, `set(key)`, `forget()`,
+`request()`, `subscribe(fn)`, `state()` (`{ asking, refused, connected }`).
+This is what the live demo does.
+
+**In the page, with one key for everyone** — prototypes and internal tools
+only, the key is in the page's code: `createAi({ provider: 'groq', apiKey })`.
+
+#### Providers
+
+Every provider here speaks the OpenAI *chat completions* API; nothing to
+install. `provider` is an id below, or `{ id, model, baseUrl, headers }` to
+change the model or reach an endpoint of your own. `AI_PROVIDERS` lists them
+(name, address, default model, where to get a key, what is free).
+
+| `provider` | Default model | Free to start | Key |
+|---|---|---|---|
+| `'openrouter'` | `openrouter/free` (a router over the free models of the day) | free models, with a free account | [openrouter.ai/keys](https://openrouter.ai/keys) |
+| `'gemini'` | `gemini-3.5-flash-lite` | free tier, rate-limited | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) |
+| `'groq'` | `openai/gpt-oss-120b` | free tier, rate-limited | [console.groq.com/keys](https://console.groq.com/keys) |
+| `'cerebras'` | `gpt-oss-120b` | free tier, rate-limited | [cloud.cerebras.ai](https://cloud.cerebras.ai/) |
+| `'mistral'` | `mistral-small-latest` | free *Experiment* plan | [console.mistral.ai/api-keys](https://console.mistral.ai/api-keys) |
+| `'openai'` | `gpt-5-mini` | — | [platform.openai.com/api-keys](https://platform.openai.com/api-keys) |
+| `'deepseek'` | `deepseek-chat` | — | [platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys) |
+| `'ollama'` | — (give `model`) | runs on your machine, no key | — |
+| `'openai-compatible'` | — (give `baseUrl` and `model`) | LM Studio, vLLM, Together, a proxy of your own… | as it needs |
+
+```js
+providerEmailModel({ provider: { id: 'groq', model: 'llama-4-scout' }, apiKey });
+providerEmailModel({ provider: { baseUrl: 'http://localhost:1234/v1', model: 'qwen3' } });
+```
+
+- Model names change often: the defaults were current at this release —
+  pass `model` to be sure of yours.
+- The answer is asked as structured output (a JSON schema); a model that
+  refuses it is asked for a JSON object, then for plain JSON — once, then
+  remembered. A model whose structured output breaks the JSON (some do on the
+  quotes of HTML) can be told to skip it: `provider: { …, format: 'text' }`.
+- The provider's failures become errors the interface explains, in its
+  language: `KEY_MISSING`, `KEY_REFUSED`, `MODEL_CREDITS`, `MODEL_BUSY`,
+  `MODEL_ERROR` (with the provider's own text in `detail`). None is a 401:
+  the key is the AI's, not the user's session.
+- **Claude**: `claudeEmailModel({ client: new Anthropic() })` with the
+  Anthropic SDK (`npm install @anthropic-ai/sdk`) — `claude-opus-5-5` by
+  default, `effort: 'medium'`, structured output, streamed so a long email
+  does not hit a request timeout — or through OpenRouter with an
+  `anthropic/…` model and one key for every model.
+- **Anything else** is a function `({ system, messages, schema, signal, task })
+  => Promise<string>` returning the JSON text — `createEmailGenerator({ model })`
+  on the server, `createAi({ model })` in the page.
+
+A generation takes from 20 seconds to a minute or two: on a server, give the
+route that long (`maxDuration` on Vercel, the proxy's timeout).
+
+What comes out is never trusted as is: shorthand padding is expanded,
+elements the builder does not edit (`mj-hero`, `mj-wrapper`, `mj-head`…) are
+turned into sections and columns, stock photos are removed (the user picks
+real images; the alt text stays), unknown variables become visible
+`[placeholders]`, and the result must pass the same validation as a saved
+template. When a problem remains, the model gets one more turn with the list.
+The prompt (`SYSTEM_PROMPT`, `buildUserPrompt`) and the purposes
+(`EMAIL_PURPOSES`) are exported from `best-email-builder/ai/server`.
+
+**Rewrite with AI.** The same generator rewrites one text: with it, selecting
+a text block or a button shows a *Rewrite with AI* section in its properties —
+*Shorter*, *Longer*, *Fix mistakes*, *Friendlier*, *More formal*, *Translate*
+(13 languages, under their own names) and a field to say what to change. The
+answer replaces the text at once, in one step of the history: Ctrl+Z brings
+the previous text back, so there is nothing to accept or compare. Selecting
+another element cancels a rewrite in progress; if the text was edited
+meanwhile, the user's words win and the answer is dropped.
+
+- On a server it is `POST {base}/rewrite`; a generator without `rewrite`
+  answers 501.
+- Every link (the same `href`, none added) and every variable (the same keys,
+  none added; a fallback after `|` may be translated) must survive, and the
+  HTML must pass the validator — otherwise the model gets one more turn, then
+  nothing is changed. A button label comes back as plain words.
+- `claudeEmailModel` asks a rewrite for `rewriteEffort: 'low'` (a few seconds);
+  a model of your own gets `task: 'rewrite'` in its request to tell the two apart.
+- `REWRITE_ACTIONS`, `REWRITE_LANGUAGES` and `REWRITE_SYSTEM_PROMPT` are
+  exported.
+
+**Suggest subjects.** Under the subject of the email, *Suggest subjects* asks
+for three other subject lines, drawn from the words of the email, each from
+its own angle (clear, curious, personal or timely). They come as a list to
+pick from, with the user's own subject first: a click puts one in the field,
+another click another one, the first row brings the user's subject back.
+*More ideas* asks for three new ones, *Done* closes the list.
+
+- On a server it is `POST {base}/subjects` (`generator.suggestSubjects`);
+  100 per user per hour.
+- The subjects are plain lines, different from the current subject and from
+  each other, in the language of the email; a merge tag is allowed only from
+  the server's catalog. Otherwise the model gets one more turn; fewer than
+  three good ones are still shown.
+- `claudeEmailModel` uses `rewriteEffort` for them as well (`task: 'subjects'`).
+  `emailWords(mjml)` (the words a reader sees) and `SUBJECTS_SYSTEM_PROMPT`
+  are exported.
+
+The live demo has no server: there, the AI runs in the page with the
+visitor's own OpenRouter key (`createAi({ provider: 'openrouter', askKey: true })`).
+
+### 5. Your brand (optional)
+
+The *Brand* button opens one dialog. Its first field is the company's
+website: *Get my brand* reads its logo, main color, headings color, font and
+name, and fills the fields below. Everything can then be changed by hand
+(upload a logo, pick a color), and a small preview follows every change.
+*Save* keeps the brand for the whole workspace:
+
+- the email being edited is repainted (the box *Also apply to this email* is
+  ticked by default) — one step of the history, Ctrl+Z brings the previous
+  look back;
+- new emails, gallery templates, inserted blocks and AI-generated emails
+  start in the brand: the logo (or the name) at the top, the name in the
+  footer, buttons and banners in the main color, headings in their color.
+
+Emails are repainted by **role**, not by exact color, so any email works —
+a template, a generated one, one built by hand: filled buttons and colored
+banners take the main color, and their text switches to white or dark
+whichever reads; bold headings take the headings color; colored links take
+the main color (or the headings color when the main one is too light to read
+on white); gray footers and body text keep theirs.
+
+```js
+import {
+  createBrandImporter,
+  createMemoryBrandRepository,
+} from 'best-email-builder/server';
+
+const handler = createEmailBuilderHandler({
+  // …
+  brandStore: createMemoryBrandRepository(), // one row: { get(), save(brand) }
+  brandImporter: createBrandImporter(),      // optional: "Get my brand"
+  rateLimits: { brandImportsPerHour: 20 },   // per user (default)
+});
+
+// In the browser:
+const storage = createHttpStorage({ brand: true }); // { brand: { import: false } } without an importer
+```
+
+- Routes: `GET {base}/brand`, `PUT {base}/brand` (write permission),
+  `POST {base}/brand/import` with `{ url }` (write permission). The import
+  saves nothing: the user reviews the result first. A logo found on the site
+  is stored like an upload (PNG, JPEG or GIF; SVG and WebP logos are skipped,
+  since most email apps do not show them — the dialog says so).
+- Without `brandImporter` the dialog has no website field; without
+  `brandStore` there is no *Brand* button.
+- Some websites refuse automated readers (bot protection answers 403): the
+  dialog says so, and the brand is filled in by hand.
+- `applyBrand(mjml, brand)` and `cleanBrand(brand)` are exported for your
+  own pipeline (e.g. rebranding stored templates).
+
+The live demo keeps the brand in `localStorage` and has no website field
+(reading a website needs a server).
+
 ## Component props
 
 | Prop | Default | Description |
@@ -286,6 +538,7 @@ With an email provider that does its own merge, map the tags instead:
 | `onSaved` | — | Called with the saved template. |
 | `onDirtyChange` | — | Called when the unsaved state changes. |
 | `dirtyCheckRef` | — | Ref receiving a function `() => boolean` (synchronous dirty check). |
+| `ai` | — | The AI module, `createAi()` from `best-email-builder/ai` (see *AI*). Without it, no AI button and no AI code. |
 
 ## Storage
 
@@ -308,6 +561,9 @@ interface TemplateStorage {
   listVariables?(): Promise<Variable[]>;                 // enable user-created variables
   saveVariable?(variable, { create }): Promise<Variable>;
   deleteVariable?(key): Promise<void>;
+  loadBrand?(): Promise<Brand>;                          // enable the Brand button
+  saveBrand?(brand): Promise<Brand>;
+  importBrand?(url, { signal }): Promise<{ brand; notes }>; // enables "Get my brand"
 }
 ```
 
@@ -396,6 +652,20 @@ touch the rest of your page, whether or not you use Tailwind yourself.
   `nosniff` and a sandboxing CSP.
 - Previews are rendered in an iframe with an empty `sandbox`.
 - Test sends are limited (10 addresses, 20 sends per user per hour by default).
+- Reading a brand from a website is a request your server makes to an address
+  a user typed, so it is fenced: http(s) on ports 80 and 443 only, no
+  credentials in the address, and every address the name resolves to must be
+  public — loopback, private networks, link-local and cloud metadata
+  (`169.254.169.254`), carrier-grade NAT, multicast and IPv4 hidden in IPv6
+  (mapped, NAT64, 6to4) are refused, at the lookup itself so a DNS answer
+  cannot slip through. Redirects (4 at most) are checked the same way. Pages,
+  stylesheets and logos have size limits after decompression, the whole
+  reading 8 seconds, and imports are limited per user (20 per hour).
+- Generated emails pass the same MJML validation as saved ones; generation is
+  limited per user (30 per hour by default) and needs the `write` permission.
+  A rewritten text keeps its links and variables (none added) and passes the
+  same validation; rewrites are limited too (200 per user per hour), and so
+  are subject ideas (100), whose merge tags come from the server's catalog.
 
 ## Development
 
@@ -434,7 +704,7 @@ channel described in [SECURITY.md](SECURITY.md).
 
 ## License
 
-[MIT](LICENSE). GrapesJS and grapesjs-mjml are BSD-3-Clause, MJML is MIT.
+[MIT](LICENSE). MJML and mjml-browser are MIT.
 
 ## Author
 

package/dist/ai-server.js

@@ -0,0 +1,68 @@
+import {
+  AI_MESSAGES,
+  AI_PROVIDERS,
+  DEFAULT_CLAUDE_MODEL,
+  EMAIL_DRAFT_SCHEMA,
+  EMAIL_PURPOSES,
+  EmailGenerationError,
+  GENERATION_ERRORS,
+  MAX_DETAILS_LENGTH,
+  PURPOSE_CATEGORIES,
+  REWRITE_ACTIONS,
+  REWRITE_LANGUAGES,
+  REWRITE_SYSTEM_PROMPT,
+  SUBJECTS_SYSTEM_PROMPT,
+  SYSTEM_PROMPT,
+  buildUserPrompt,
+  claudeEmailModel,
+  cleanGenerateInput,
+  createEmailGenerator,
+  createRewriter,
+  createSubjectSuggester,
+  emailWords,
+  normalizeGeneratedMjml,
+  parseDraft,
+  providerEmailModel,
+  purposeById,
+  purposesByCategory,
+  resolveProvider,
+  reviewDraft,
+  reviewRewrite,
+  reviewSubjects
+} from "./chunk-MPX5CWTZ.js";
+import "./chunk-2RZHGAH5.js";
+import "./chunk-5SASKCUC.js";
+import "./chunk-DFNHICTF.js";
+export {
+  AI_MESSAGES,
+  AI_PROVIDERS,
+  DEFAULT_CLAUDE_MODEL,
+  EMAIL_DRAFT_SCHEMA,
+  EMAIL_PURPOSES,
+  EmailGenerationError,
+  GENERATION_ERRORS,
+  MAX_DETAILS_LENGTH,
+  PURPOSE_CATEGORIES,
+  REWRITE_ACTIONS,
+  REWRITE_LANGUAGES,
+  REWRITE_SYSTEM_PROMPT,
+  SUBJECTS_SYSTEM_PROMPT,
+  SYSTEM_PROMPT,
+  buildUserPrompt,
+  claudeEmailModel,
+  cleanGenerateInput,
+  createEmailGenerator,
+  createRewriter,
+  createSubjectSuggester,
+  emailWords,
+  normalizeGeneratedMjml,
+  parseDraft,
+  providerEmailModel,
+  purposeById,
+  purposesByCategory,
+  resolveProvider,
+  reviewDraft,
+  reviewRewrite,
+  reviewSubjects
+};
+//# sourceMappingURL=ai-server.js.map