best-email-builder 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,192 @@ 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.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
+- **`TemplateLibrary`** — the first screen: a template bank in three columns
+  (searchable list of your templates and of the ready-made bases, details of
+  the selected one, rendered preview on desktop / mobile). *Edit*, *New
+  template* and *Start from this base* hand the template to the host through
+  `onEdit` / `onCreate`; *Duplicate*, *Delete*, *Copy HTML* and *Download*
+  work in place. *Favorites*: the star of the details moves an entry to a
+  section at the top (`favoritesKey`). Search with Ctrl+K, Esc clears it.
+  Follows its own width down to phones. French included.
+- **`EmailStudio`** — `TemplateLibrary` and `EmailBuilder` wired together.
+  Each screen still works alone.
+  The editor opened from the bank has no *Templates* button: the bases are
+  picked in the bank, and the gallery would replace the email being edited
+  (`builderProps.templates` brings it back).
+- **Two entry points, one per block**: `best-email-builder/library` (block A,
+  the bank — no editor, no GrapesJS) and `best-email-builder/builder`
+  (block B, the editor — nothing of the bank). A unit test bundles each one
+  and fails if it reaches the other. The README shows block B under a bank
+  of your own (what to pass in, what comes back) and block A with your own
+  editor; a story drives block B from a home-made bank.
+- Storage contract: optional `list()` and `remove(id)`, implemented by
+  `createHttpStorage()` (the server already had the routes) and
+  `createMemoryStorage()`.
+- `withPlaceholderImages(html)` draws a grey frame for images not chosen yet
+  in compiled HTML.
+
+### Changed
+- Demo, three pages: a landing page (a background that follows the pointer,
+  a marquee of the editors it can replace, a new mark), the template bank,
+  and the editor — each page has its own address (`#/templates`,
+  `#/editor/…`), so a reload keeps it. The bank and the editor share one
+  window of the same size, under a bar with the steps and a *Full screen* /
+  *Exit full screen* button. Type: Geist, Bricolage Grotesque for the title.
+- Thin scrollbars everywhere in the builder and the
+  bank, inside the canvas and the preview frames (preview only, never the
+  saved HTML): a 5.6 px gutter, a thin thumb, no arrows, shown only while the
+  pointer is over the block. They also replace GrapesJS's own dark ones.
+- The preview (in the bank and in the editor's *Preview*) switches device
+  with the editor toolbar's switch, and narrows and widens like the canvas
+  (350 ms).
+- `types` and `typesVersions` in `package.json`: TypeScript projects still on
+  `moduleResolution: "node"` find the types of every entry (`.`, `/builder`,
+  `/library`, `/server`).
+- `EmailBuilder` no longer imports the package entry
+  (`createDefaultEmailEditor` lives in its own module).
+
+### Fixed
+- Demo: after a first save, switching the language reopened a blank editor
+  (or the base), and saving again created a duplicate; it now reopens the
+  saved template.
+
 ## [0.2.0] — 2026-10-12
 
 ### 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,23 +32,52 @@ 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.
+  Claude out of the box; any other model in a few lines.
+- **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.
+- **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.
+  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,
   insertion at the caret, in the subject line too, sample values for the
   preview and fallbacks for recipients without a value.
@@ -56,9 +86,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
 ```
 
@@ -103,6 +134,106 @@ component (the canvas needs the DOM). With Next.js, load it with
 `dynamic(() => import(...), { ssr: false })` or render it from a
 `'use client'` component.
 
+### Two blocks, each one on its own
+
+The package has two blocks. An application installs one, the other, or both,
+and each has its own entry point, so one never brings the other's code:
+
+| Block | Import | What it is |
+|---|---|---|
+| 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
+same stylesheet, `best-email-builder/styles.css`.
+
+#### A + B, nothing to wire
+
+```jsx
+import { EmailStudio, createHttpStorage } from 'best-email-builder';
+
+<EmailStudio storage={createHttpStorage()} locale="fr" sender={sender} />
+```
+
+#### Block B with your own library
+
+Your library (a table, a sidebar, a modal — anything) only decides what the
+editor opens, and hears back when it saves or closes:
+
+| 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 }}` |
+| start from a blank email | neither |
+| refresh its list after a save | `onSaved={(template) => …}` — `template.id` is set from the first save on |
+| show itself again | `onClose={() => …}` (the *Back* button) |
+| hide the editor's own gallery of bases | `templates={[]}` |
+
+Give the editor a `key` that changes with what it opens, so switching from one
+template to another starts a fresh editor.
+
+```jsx
+import { useState } from 'react';
+import { EmailBuilder, createHttpStorage } from 'best-email-builder/builder';
+
+const storage = createHttpStorage();
+
+function Emails() {
+  const [open, setOpen] = useState(null); // null = my library
+
+  if (!open) {
+    return (
+      <MyTemplateList                                     // your block A
+        onOpen={(id) => setOpen({ key: id, templateId: id })}
+        onNew={() => setOpen({ key: `new-${Date.now()}` })}
+      />
+    );
+  }
+  return (
+    <EmailBuilder
+      key={open.key}
+      storage={storage}
+      locale="fr"
+      templates={[]}
+      templateId={open.templateId ?? null}
+      initialMjml={open.mjml}
+      initialMeta={open.meta}
+      onSaved={() => refreshMyList()}
+      onClose={() => setOpen(null)}
+    />
+  );
+}
+```
+
+Your list can read the same templates with `storage.list()` (summaries, newest
+first) or from your own API — the editor only needs the `id`.
+
+#### Block A with your own editor
+
+```jsx
+import { TemplateLibrary, createHttpStorage } from 'best-email-builder/library';
+
+<TemplateLibrary
+  storage={createHttpStorage()}
+  locale="fr"
+  onEdit={(template) => router.push(`/emails/${template.id}`)}
+  onCreate={(start) => openMyEditor(start)}   // start: null (new), or { baseId, mjml, meta: { subject, preheader } }
+  onClose={closeModal}                        // optional: shows a close button
+/>
+```
+
+The library needs `storage.list()`; *Delete* appears when the storage has
+`remove()`, the preview uses `render()` (else the HTML compiled at the last
+save). Its props: `storage`, `locale`, `messages`, `onNotify`, `sender`,
+`templates` (the bases, `[]` hides them), `title`, `description`,
+`selectedId`, `favoritesKey` (the star of the details moves an entry to a
+*Favorites* section at the top; kept in `localStorage` under this key, `null`
+turns favorites off), `onEdit`, `onCreate`, `onClose`, `className`. Like the
+builder, it fills its parent and follows its own width (three columns, then
+two, then list and details as two screens).
+
 ### 2. The server routes
 
 ```js
@@ -167,6 +298,150 @@ 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. Generating emails with AI (optional)
+
+The *Generate* button 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.
+
+The model runs on the server, where its key is:
+
+```js
+import Anthropic from '@anthropic-ai/sdk';   // npm install @anthropic-ai/sdk
+import {
+  createEmailBuilderHandler,
+  createEmailGenerator,
+  claudeEmailModel,
+  compileMjml,
+} from 'best-email-builder/server';
+
+const handler = createEmailBuilderHandler({
+  /* … */
+  generator: createEmailGenerator({
+    model: claudeEmailModel({ client: new Anthropic() }), // ANTHROPIC_API_KEY
+    compile: compileMjml, // MJML's own warnings go back to the model
+  }),
+  rateLimits: { generatePerHour: 30, rewritePerHour: 200, subjectsPerHour: 100 }, // per user (defaults)
+});
+```
+
+```jsx
+<EmailBuilder storage={createHttpStorage({ generate: true })} />
+```
+
+- `claudeEmailModel({ client, model, effort, maxTokens })` — `claude-opus-5-5`
+  by default, `effort: 'medium'`; the answer is structured output (a JSON
+  schema: name, subject, preheader, MJML) and is streamed, so a long email does
+  not hit a request timeout. A generation takes from 20 seconds to a minute or
+  two: give the route that long (`maxDuration` on Vercel, the proxy's timeout).
+- **Another provider** is a function `({ system, messages, schema, signal, task }) =>
+  Promise<string>` returning the JSON text — pass it as `model`.
+- 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, to read or to build on.
+
+**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.
+
+- It is `POST {base}/rewrite`, enabled with `createHttpStorage({ generate: true })`
+  like generation; 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);
+  another provider 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.
+
+- It is `POST {base}/subjects` (`generator.suggestSubjects`), enabled with
+  `createHttpStorage({ generate: true })` too; 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, *Generate*, *Rewrite with AI* and
+*Suggest subjects* ask for the visitor's own Anthropic key, keep it in the
+browser and call Anthropic directly.
+
+### 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 |
@@ -194,7 +469,9 @@ or use `createHttpStorage()` with the server handler:
 
 ```ts
 interface TemplateStorage {
+  list?(): Promise<Template[]>;            // TemplateLibrary: newest first, no document/MJML
   load(id): Promise<Template>;
+  remove?(id): Promise<void>;              // TemplateLibrary: enables Delete
   create(payload): Promise<{ template; warnings }>;
   duplicate(id): Promise<{ template; warnings }>;
   save(id, payload): Promise<{ template; warnings; version }>;
@@ -202,10 +479,16 @@ interface TemplateStorage {
   getVersion(id, versionId): Promise<Version & { document; mjml }>;
   uploadImage(file): Promise<{ path }>;
   render?(input): Promise<{ html; warnings; quality }>;   // enables Preview
+  generate?(input, { signal }): Promise<{ name; subject; preheader; mjml; warnings }>; // enables Generate
+  rewrite?(input, { signal }): Promise<{ text }>;        // enables Rewrite with AI
+  suggestSubjects?(input, { signal }): Promise<{ subjects }>; // enables Suggest subjects
   sendTest?(input): Promise<{ sent; failed; invalid; results }>; // enables Send test
   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"
 }
 ```
 
@@ -294,6 +577,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
 
@@ -332,7 +629,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/builder.js

@@ -0,0 +1,44 @@
+import {
+  EmailBuilder,
+  EmailBuilderBoundary
+} from "./chunk-MY6WPDT4.js";
+import {
+  STARTER_MJML,
+  StorageError,
+  TEMPLATE_GALLERY,
+  buildGallery,
+  createHttpStorage,
+  createMemoryStorage,
+  createStarterMjml
+} from "./chunk-AT73Y7JA.js";
+import "./chunk-JNHFZXDL.js";
+import {
+  CUSTOM_GROUP,
+  DEFAULT_VARIABLES,
+  EMAIL_BUILDER_VERSION,
+  LOCALES,
+  createTranslator,
+  defineVariables,
+  mergeVariables,
+  translatorFor
+} from "./chunk-HHLOE6OZ.js";
+export {
+  CUSTOM_GROUP,
+  DEFAULT_VARIABLES,
+  EMAIL_BUILDER_VERSION,
+  EmailBuilder,
+  EmailBuilderBoundary,
+  LOCALES,
+  STARTER_MJML,
+  StorageError,
+  TEMPLATE_GALLERY,
+  buildGallery,
+  createHttpStorage,
+  createMemoryStorage,
+  createStarterMjml,
+  createTranslator,
+  defineVariables,
+  mergeVariables,
+  translatorFor
+};
+//# sourceMappingURL=builder.js.map

package/dist/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}