@seliseblocks/mailcraft 0.1.0 → 0.2.0

package/DOCS.md

@@ -45,9 +45,9 @@ A user drags rows and blocks onto a canvas, edits text in place, styles it in an
 | Runtime dependencies | none |
 | Framework | none — a custom element works in React, Angular, Vue, Svelte and plain HTML |
 | Isolation | Shadow DOM; the editor's CSS and the host's cannot reach each other |
-| Size | ~553 KB minified, ~152 KB gzipped, one file |
+| Size | ~639 KB minified, ~172 KB gzipped, one file |
 | Languages | 31, RTL automatic |
-| Content blocks | 18 — text, heading, image, button, divider, spacer, social, video, countdown, menu, list, table, box, html, css, code, svg, embed |
+| Content blocks | 20 — text, heading, image, button, divider, spacer, social, video, countdown, menu, list, table, box, html, css, code, svg, embed, condition, loop |
 
 ---
 
@@ -70,9 +70,9 @@ Exported HTML is valid input to the importer, so **saving the export is saving t
 
 The internal document still exists. It is simply not yours to hold.
 
-### 2. The editor never makes a network request
+### 2. The editor never talks to a backend of its own
 
-There is no `fetch` anywhere in the package. No base URL, no auth, no upload endpoint, no telemetry.
+No base URL, no auth, no upload endpoint, no telemetry. The one `fetch` in the package is the screenshot capture inlining the images *your template already shows* so they can be drawn into the PNG — best-effort and CORS-bound, and an image the remote server refuses degrades to a blank pixel rather than a failed capture.
 
 Image storage is a plain object the host assigns:
 
@@ -119,6 +119,12 @@ import '@seliseblocks/mailcraft';   // side effect: registers <mailcraft-editor>
 
 Named exports (`MailCraftEditor`, `EditorCore`, `LOCALES`, `validateFiles`, …) come from the same entry.
 
+**TypeScript** works out of the box — the package ships declarations (`types/index.d.ts`) for every named export, and registers `mailcraft-editor` in `HTMLElementTagNameMap`, so `document.createElement('mailcraft-editor')` and `querySelector('mailcraft-editor')` come back typed. The contract types (`StorageProvider`, `StorageLimits`, `Asset`, `ToolbarOption`, `FooterOption`, `CreateEditorOptions`, …) are exported for your own signatures:
+
+```ts
+import type { StorageProvider, StorageLimits } from '@seliseblocks/mailcraft';
+```
+
 **Server-side rendering:** the module defines a custom element, so import it in the browser only — inside a `useEffect`, an `onMounted`, or a `dynamic(..., { ssr: false })` component.
 
 Without a bundler:
@@ -233,7 +239,7 @@ Templates are host content **and** host UI. The editor ships no catalogue and ha
 editor.loadTemplate({ name: 'Welcome', html });
 ```
 
-Applying one is a normal undoable edit with a toast, and your string is never mutated. Ready-made examples live in [`examples/templates/`](https://github.com/SELISEdigitalplatforms/blocks-mailcraft/tree/main/examples/templates) with a working picker in [`examples/vanilla.html`](examples/vanilla.html) — both host-app content, shipped in the package for you to lift but not part of its API.
+Applying one is a normal undoable edit with a toast, and your string is never mutated. Ready-made examples ship in the package under `examples/templates/`, with a working picker in [`examples/vanilla.html`](examples/vanilla.html) — both host-app content, shipped in the package for you to lift but not part of its API.
 
 ## Merge variables
 
@@ -243,9 +249,27 @@ Applying one is a normal undoable edit with a toast, and your string is never mu
 
 Users insert them from the toolbar; they export as `{{first_name}}`.
 
+### Conditions and loops
+
+**Condition** and **Loop** are blocks in the palette. Dropping one inserts a *pair* of markers — a start band and an end band — and everything the user drags between them is what the logic applies to. Dropped inside a column, the pair wraps blocks; dropped onto the canvas between sections, each marker gets a slim row of its own, so whole sections can be moved between them. From then on each half is an ordinary block: moved, duplicated or deleted independently.
+
+Like merge tags, the editor never evaluates the expressions — the export emits literal Handlebars-style tags at the markers' positions for your templating engine to run at send time:
+
+```html
+{{#if has_order}}
+{{#each order.items}}
+…whatever sits between the markers, once per item…
+{{/each}}
+{{/if}}
+```
+
+The exporter balances the document as a whole: a stray end marker emits nothing, and a start whose end was deleted is auto-closed after the last row, so the output template is always well-formed. Marker-only rows emit just the tag — no empty `<tr>` band reaches a recipient — and inside a loop, item-scoped merge tags (`{{ this.name }}`, `{{ price }}`) pass through like any other token. The markers render as dashed teal `SHOW IF` / violet `REPEAT EACH` bands on the canvas, in the preview, and in the code view's live pane — every editor surface shows the template the way it shows merge tokens — while a recipient sees nothing but the engine's output. Exported tags round-trip: re-importing the HTML restores them as marker blocks in the same positions.
+
+A start marker's expression field suggests the host's `variables` in a dropdown but stays free text, since conditions and loops routinely reference names that aren't inline tokens (`order.items`, a boolean flag, whatever your engine understands).
+
 ## Image uploads
 
-Both properties are required. Without them the library keeps its built-in demo files and every upload is refused.
+Both properties are required. The package ships no files of its own: with no provider the library opens empty and holds only what is dropped into it — data URIs, kept in the local draft, which no email client renders. With a provider but no limits every upload is refused.
 
 ```js
 editor.storageLimits = {
@@ -294,7 +318,9 @@ editor.storageProvider = { list, upload, limits: { accept: [...], maxBytes: 5e6
 
 The two are merged **per key**, with `editor.storageLimits` winning — so a provider can ship sane defaults and the host can still tighten one number without restating the rest. Either source satisfies the "limits are required" rule; only a file that passes the merged result reaches `upload`.
 
-Setting `editor.storageProvider = null` puts the built-in demo library back, which is what an unconfigured editor shows.
+Setting `editor.storageProvider = null` drops back to that empty local library.
+
+`examples/vanilla.html` wires a working provider over IndexedDB — latency, cursor paging, server-side folders and search, uploads that survive a reload, deletes that stay deleted. It is the shape of a real integration with `fetch` swapped out, and it is where every file in the live demo's Assets modal comes from.
 
 ## Choosing what the top bar shows
 
@@ -399,6 +425,8 @@ Override any individual string:
 editor.messages = { 'action.export': 'Send to campaign' };
 ```
 
+Every key, with its English default, is listed in [Every message key](#every-message-key). English is always the floor: a key your table leaves out shows the built-in English rather than a gap, and `missingKeys(yourTable)` tells you what a full replacement still lacks.
+
 ## Matching your app's typography
 
 ```html
@@ -480,7 +508,7 @@ template, not to your app.
 | `.uiFont` | string |
 | `.accent` | string |
 | `.messages` | `{ key: string }` |
-| `.storageProvider` | `{ list, upload, folders?, remove?, limits? }` — `null` restores the built-in library |
+| `.storageProvider` | `{ list, upload, folders?, remove?, limits? }` — `null` drops back to the empty local library |
 | `.storageLimits` | `{ accept, maxBytes, maxWidth?, maxHeight?, maxFilesPerDrop?, allowSvg? }`, merged over `provider.limits` per key |
 | `.aiProvider` | `async (prompt) => text` |
 | `.iconProvider` | `(platformKey, { label, size, color }) => Node` — social-icon override; falls back to the built-in icon when it is unset, throws, or returns a non-node |
@@ -495,7 +523,7 @@ template, not to your app.
 | `LOCALES`, `LOCALE_TABLES`, `createTranslator` | i18n: the shipped tags, their tables, and the translator the editor uses |
 | `defineMessages(base, overrides)` | merge a shipped locale with your own overrides — the supported way to build a `.messages` value |
 | `missingKeys(locale, base)` | keys `base` has that `locale` does not translate. What a translator has left to do |
-| `EN`, `MESSAGE_KEYS` | the English table and every key in it |
+| `EN`, `MESSAGE_KEYS` | the English table and every key in it — listed in [Every message key](#every-message-key) |
 | `isRtl(tag)` | whether a locale tag is right-to-left. Metadata — `dir` is what actually flips the layout |
 | `validateFiles`, `acceptAttribute`, `sanitizeName` | upload validation, reusable outside the editor |
 | `limitsProblem(limits)` | what a limits object is missing, if anything — the check that refuses uploads |
@@ -526,6 +554,206 @@ template, not to your app.
 
 `getContent()` / `setContent(doc)` expose the internal document. They exist because undo, autosave and the test suite need them. The shape is free to change between versions — store `exportHtml()` instead.
 
+### Every message key
+
+The complete catalog of UI strings that `.messages` accepts — every key the editor ever asks for, with its built-in English text. In code the same catalog is `EN` (keys with values) and `MESSAGE_KEYS` (just the keys), and `missingKeys(yourTable)` diffs a custom table against it.
+
+<!-- message-keys:begin — generated by build.js from src/core/i18n/en.js; edit en.js and run `node build.js`, never this table. -->
+
+| key | English default |
+|---|---|
+| `action.aiDraft` | Draft |
+| `action.aiDraftHint` | Draft email content with AI |
+| `action.applyToCanvas` | Apply to canvas |
+| `action.applyToCanvasHint` | Parse the source back into editable rows |
+| `action.chromeHint` | Light / dark editor chrome |
+| `action.chromeHintToDark` | Dark mode |
+| `action.chromeHintToLight` | Light mode |
+| `action.chromeToDark` | Dark |
+| `action.chromeToLight` | Light |
+| `action.close` | Close |
+| `action.closeWithoutApplyingHint` | Close without applying |
+| `action.code` | Code |
+| `action.codeHint` | Edit the raw HTML with a live preview |
+| `action.deleteHint` | Delete — ⌫ |
+| `action.download` | Download |
+| `action.downloadPng` | Download PNG |
+| `action.duplicateHint` | Duplicate — ⌘D |
+| `action.export` | Export |
+| `action.exportHint` | Export your email |
+| `action.preview` | Preview |
+| `action.previewHint` | Preview the email |
+| `action.redoHint` | Redo — ⌘⇧Z |
+| `action.reload` | Reload |
+| `action.reloadHint` | Reload the source from the canvas |
+| `action.screenshot` | Screenshot |
+| `action.screenshotHint` | Preview the full template as an image, then download it |
+| `action.undoHint` | Undo — ⌘Z |
+| `action.upload` | Upload |
+| `ai.actionInsertButton` | Insert as button |
+| `ai.actionInsertHeading` | Insert as heading |
+| `ai.actionInsertText` | Insert as text block |
+| `ai.briefLabel` | What is this email about? |
+| `ai.briefPlaceholder` | e.g. Autumn outerwear drop, 15% for subscribers, free shipping over $150 |
+| `ai.disclosure` | AI creates suggestions from your brief. Review and edit the result before sending. |
+| `ai.generate` | Generate draft with AI |
+| `ai.goal` | Goal |
+| `ai.kindBody` | Body copy |
+| `ai.kindButton` | Button label |
+| `ai.kindHeadline` | Headline |
+| `ai.tone` | Tone |
+| `ai.writing` | Writing… |
+| `blocks.count` | {count} blocks |
+| `blocks.dragHint` | Drag a block onto the canvas |
+| `canvas.meta` | {rows} rows · {blocks} blocks · {width}px |
+| `code.applyNote` | Apply parses each top-level table row back into a canvas row you can still select, reorder and delete — hand-written markup survives the round trip. |
+| `code.liveHtmlPreviewTitle` | Live HTML preview |
+| `code.livePreview` | Live preview |
+| `code.meta` | {kb} KB · {lines} lines |
+| `code.source` | Source |
+| `code.statusEdited` | Code view — edited — preview live, not yet applied |
+| `code.statusSynced` | Code view — in sync with the canvas |
+| `device.desktop` | Desktop |
+| `device.desktopHint` | Desktop width |
+| `device.mobile` | Mobile |
+| `device.mobileHint` | Mobile width |
+| `export.copied` | Copied |
+| `export.copy` | Copy email |
+| `export.meta` | {kb} KB · ready to copy or download |
+| `files.dragToCanvas` | Drag any file straight onto the canvas to place it as an image block. |
+| `files.libraryCount` | Library — {count} files |
+| `files.openManager` | Open file manager |
+| `footer.poweredBy` | Powered by SELISE Blocks © 2026 |
+| `inspector.blockProperties` | Block properties |
+| `inspector.emptyBody` | Pick a row or block on the canvas to style it here. Drag blocks in from the <strong style="color: var(--ed-text); font-weight: 600;">Content blocks</strong> tab; double-click any text to edit it in place. |
+| `inspector.nothingSelected` | Nothing selected |
+| `inspector.sectionLabel` | Section |
+| `inspector.sectionProperties` | Section properties |
+| `inspector.shortcuts` | Shortcuts |
+| `inspector.title` | Inspector |
+| `layers.blockCount` | {count} blocks |
+| `layers.column` | Column {index} |
+| `layers.sectionMulti` | Section · {count} columns |
+| `layers.sectionSingle` | Section |
+| `layers.structure` | Structure |
+| `library.allFiles` | All files |
+| `library.clickToPlace` | Click a file to place it · drag a file onto the canvas |
+| `library.clickToReplace` | Click a file to replace the selected image |
+| `library.del` | DEL |
+| `library.deleteFileHint` | Delete file |
+| `library.dropHint` | Drop image files here to upload — or use the Upload button. |
+| `library.empty` | No files here yet. |
+| `library.folders` | Folders |
+| `library.loadMore` | Load more |
+| `library.searchPlaceholder` | Search files… |
+| `library.storageLabel` | {count} files · {size} |
+| `modal.aiDraft` | AI writing assistant |
+| `modal.aiDraftTitle` | Draft your email with AI |
+| `modal.assetsTitle` | Assets |
+| `modal.export` | Export |
+| `modal.exportTitle` | Your email is ready |
+| `modal.fileManager` | File manager |
+| `modal.rawHtmlTitle` | Raw HTML, live preview |
+| `modal.replaceImage` | Replace image |
+| `preview.kickerDesktop` | Preview — desktop {width}px |
+| `preview.kickerMobile` | Preview — mobile 375px |
+| `rows.canvasModel` | Canvas model |
+| `rows.customMarkup` | Custom markup |
+| `rows.hintRows` | Section based: drop a layout first, then drop blocks into its columns — every section carries its own background, border, flex or grid settings. |
+| `rows.hintStack` | Free stack: skip layouts — every block you drop becomes its own full-width section, stacked in order. |
+| `rows.htmlRowHint` | Drag in, or click to append — a full-bleed row you fill with raw HTML |
+| `rows.modeFreeStack` | Free stack |
+| `rows.modeRowBased` | Row based |
+| `rows.rawHtmlDesc` | Full-bleed section, your markup, still draggable |
+| `rows.rawHtmlSection` | Raw HTML section |
+| `rows.sectionLayouts` | Section layouts |
+| `rte.clearFormatting` | Clear formatting |
+| `rte.highlightColor` | Highlight color |
+| `rte.mergeTags` | Merge Tags |
+| `rte.noMergeTags` | No merge tags available |
+| `rte.removeHighlight` | Remove highlight |
+| `rte.textColor` | Text color |
+| `rte.textStyle` | Text style |
+| `shortcut.delete` | ⌫ — delete selection |
+| `shortcut.duplicate` | ⌘D — duplicate selection |
+| `shortcut.escape` | ESC — deselect, close |
+| `shortcut.export` | ⌘E — export email |
+| `shortcut.undoRedo` | ⌘Z / ⌘⇧Z — undo, redo |
+| `status.autosaveOn` | autosave on |
+| `status.saveFailed` | not saved — storage full |
+| `status.saved` | saved {time} |
+| `storage.errDeleteFailed` | {name} could not be deleted — {reason} |
+| `storage.errDimensions` | {name} is {w}×{ht}px — the limit is {maxW}×{maxH}px. |
+| `storage.errFormat` | {name} is a {type} file, which is not allowed here. |
+| `storage.errLoadFailed` | The file library could not be loaded — {reason} |
+| `storage.errNoAccept` | Uploads are switched off: no file formats have been allowed. |
+| `storage.errNoLimits` | Uploads are switched off: this app has not set any upload limits. |
+| `storage.errNoMaxBytes` | Uploads are switched off: no maximum file size has been set. |
+| `storage.errSvg` | {name} is an SVG, which this app does not accept. |
+| `storage.errTooLarge` | {name} is {size} — the limit is {max}. |
+| `storage.errTooMany` | Only {max} files can be uploaded at once. |
+| `storage.errUnreadable` | {name} is not a readable image. |
+| `storage.errUploadFailed` | {name} could not be uploaded — {reason} |
+| `storage.loading` | Loading files… |
+| `storage.uploading` | Uploading {count}… |
+| `story.copy` | Copy |
+| `story.failed` | Screenshot failed |
+| `story.failedHint` | An image in the template could not be loaded for capture. |
+| `story.kicker` | Screenshot |
+| `story.meta` | {w}×{h} · screen {i} of {n} |
+| `story.pause` | Pause |
+| `story.play` | Play |
+| `story.rendering` | Rendering the screenshot |
+| `story.renderingHint` | Painting every block at 2× — this takes a moment on a long template. |
+| `story.replay` | Replay |
+| `story.retry` | Try again |
+| `tab.blocks` | Content blocks |
+| `tab.blocksHint` | Content blocks and variables |
+| `tab.data` | Variables |
+| `tab.dataHint` | Variables provided by your code |
+| `tab.design` | Design |
+| `tab.designHint` | Style the selection |
+| `tab.files` | Assets |
+| `tab.filesHint` | Asset library |
+| `tab.layers` | Layers |
+| `tab.layersHint` | Document structure |
+| `tab.rows` | Sections |
+| `tab.rowsHint` | Section layouts and canvas model |
+| `tab.settings` | Settings |
+| `tab.settingsHint` | Email settings |
+| `toast.assetDeleted` | {name} deleted |
+| `toast.buttonAdded` | Button added |
+| `toast.duplicated` | Duplicated |
+| `toast.fileUploadedMany` | {count} files uploaded |
+| `toast.fileUploadedOne` | 1 file uploaded |
+| `toast.headingAdded` | Heading added |
+| `toast.htmlCopied` | HTML copied to clipboard |
+| `toast.imageAdded` | Image added to canvas |
+| `toast.imageReplaced` | Image replaced |
+| `toast.parseError` | Could not parse that HTML |
+| `toast.pngCopied` | Screenshot copied to clipboard |
+| `toast.pngCopyFailed` | This browser would not accept an image on the clipboard |
+| `toast.pngFailed` | Screenshot failed — an external image could not be loaded |
+| `toast.pngSaved` | Screenshot downloaded |
+| `toast.snippetCopied` | {name} copied — select a text block to insert it |
+| `toast.snippetDefaultLabel` | Snippet |
+| `toast.snippetInserted` | {name} inserted |
+| `toast.sourceAppliedMany` | Source applied — {rows} rows back on the canvas |
+| `toast.sourceAppliedOne` | Source applied — 1 row back on the canvas |
+| `toast.sourceReloaded` | Source reloaded from canvas |
+| `toast.templateLoaded` | {name} loaded |
+| `toast.textBlockAdded` | Text block added |
+| `vars.declaredNote` | Declared by your application — the canvas always shows the token, never a value. |
+| `vars.filterPlaceholder` | Filter variables… |
+| `vars.fromCode` | {count} from your code |
+| `vars.insert` | insert |
+| `vars.insertHint` | Click to insert into the selected text, heading or button |
+| `vars.noMatch` | No variable matches that filter. |
+| `vars.noneDeclared` | Your application has not declared any variables yet. |
+| `vars.rteHint` | While editing text you can also pick a variable straight from the inline toolbar’s dropdown. |
+| `vars.title` | Variables |
+<!-- message-keys:end -->
+
 ---
 
 # How it works inside
@@ -545,12 +773,12 @@ Useful when debugging an integration, and required reading before contributing.
 **Build.** `build.js` is a zero-dependency bundler that turns the ESM sources into one plain `<script>`, then minifies through esbuild with a sourcemap alongside. esbuild is a dev dependency only — consumers install nothing transitive, and a clone with no `node_modules` still produces a working bundle.
 
 ```sh
-npm install       # one devDependency (esbuild)
+npm install       # devDependencies only: esbuild (minify), jsdom (DOM tests), c8 (coverage)
 node build.js     # rebuild dist/ after any change under src/
-npm test          # storage, export, templates, toolbar, system — no DOM needed
+npm test          # 13 suites — core logic runs DOM-free, the editor/importer suites run on jsdom
 ```
 
-Deeper notes for contributors and coding agents live in [AGENTS.md](https://github.com/SELISEdigitalplatforms/blocks-mailcraft/blob/main/AGENTS.md).
+Deeper notes for contributors and coding agents live in `AGENTS.md` in the repository, alongside [CONTRIBUTING](https://mailcraft.seliseblocks.com/CONTRIBUTING.html), which is also on the docs site.
 
 ---
 

package/README.md

@@ -42,6 +42,7 @@ Exported HTML is valid input to `loadTemplate`, so saving the export *is* saving
 | | |
 |---|---|
 | `variables="first_name,company"` | merge tags, exported as `{{first_name}}` |
+| Condition / Loop blocks | dynamic content — exported as `{{#if …}}` / `{{#each …}}` for your sending engine |
 | `locale="de"` | 31 languages, RTL automatic |
 | `theme="light" \| "dark"` | host owns light/dark; hides the built-in toggle |
 | `ui-font="inherit"` | match your app's font |
@@ -53,7 +54,7 @@ Exported HTML is valid input to `loadTemplate`, so saving the export *is* saving
 | `.aiProvider` | `async (prompt) => text`, powers the AI draft panel |
 | `.messages` | override any UI string |
 
-Every attribute is also a property. Full reference and integration recipes: **[DOCS.md](DOCS.md)**.
+Every attribute is also a property. TypeScript declarations ship with the package. Full reference and integration recipes: **[DOCS.md](DOCS.md)**.
 
 ## For AI agents
 
@@ -63,6 +64,8 @@ Everything an assistant needs to wire this up correctly:
 PACKAGE   @seliseblocks/mailcraft — Web Component, zero runtime deps
 IMPORT    import '@seliseblocks/mailcraft'   (side effect: registers the element)
           Safe to import under SSR; the element itself renders in a browser only.
+TYPES     TypeScript declarations ship in the package (types/index.d.ts) for every
+          named export; 'mailcraft-editor' is registered in HTMLElementTagNameMap.
 ELEMENT   <mailcraft-editor id="editor"></mailcraft-editor>
 MOUNT     createEditor(target, options) -> handle   (no tag needed)
           target  = CSS selector or Element; throws if it matches nothing
@@ -79,6 +82,9 @@ DATA      HTML in, HTML out. There is no JSON document format in the public API.
           editor.exportHtml() -> string         send-ready email HTML
           Persist by storing exportHtml() and passing it back to loadTemplate().
           Unclassifiable markup survives as a raw-HTML block. Nothing is dropped.
+          Condition/Loop blocks export literal {{#if expr}}/{{#each expr}} tags
+          (always balanced) for the host's templating engine; never evaluated
+          by the editor, and re-import restores them as blocks.
 
 EVENTS    'change'  detail = internal doc (do not persist this)
           'export'  detail = HTML string
@@ -102,8 +108,10 @@ UPLOADS   Limits and a provider are both required, or every upload is refused.
           editor.storageProvider = { list(q), upload(file, o), folders?(), remove?(a),
                                      limits? }
           provider.limits is merged per key under .storageLimits, and satisfies
-          the requirement on its own. .storageProvider = null restores the demo library.
-          The editor never makes a network request itself.
+          the requirement on its own. With no provider the library is empty and
+          local to the draft — the package ships no files of its own.
+          The editor never talks to a backend of its own; its only fetch is the
+          screenshot capture inlining the template's own images.
 
 TOOLBAR   Parts: logo status device undo redo theme ai code preview export
           Attribute = allow-list (keep these). Property = { part: false } (drop these).

package/README.md.txt

@@ -0,0 +1,134 @@
+# MailCraft
+
+Drag-and-drop email editor as a Web Component. No dependencies, no framework, no build step.
+
+**[Live demo](https://mailcraft.seliseblocks.com/examples/vanilla.html)** · **[Documentation](https://mailcraft.seliseblocks.com/DOCS.html)**
+
+```sh
+npm install @seliseblocks/mailcraft
+```
+
+## Use
+
+```js
+import '@seliseblocks/mailcraft';   // registers <mailcraft-editor>
+```
+
+```html
+<mailcraft-editor id="editor"></mailcraft-editor>
+```
+
+Or mount it into a container from code, without writing the tag:
+
+```js
+import { createEditor } from '@seliseblocks/mailcraft';
+
+const editor = createEditor('#mail', { html, toolbar: false });
+editor.exportHtml();
+editor.destroy();
+```
+
+That is a working editor. It speaks HTML in both directions — there is no document format to store or migrate:
+
+```js
+editor.loadTemplate({ name: 'Welcome', html });   // give it HTML
+const html = editor.exportHtml();                 // get send-ready HTML back
+```
+
+Exported HTML is valid input to `loadTemplate`, so saving the export *is* saving the user's work.
+
+## Configure
+
+| | |
+|---|---|
+| `variables="first_name,company"` | merge tags, exported as `{{first_name}}` |
+| Condition / Loop blocks | dynamic content — exported as `{{#if …}}` / `{{#each …}}` for your sending engine |
+| `locale="de"` | 31 languages, RTL automatic |
+| `theme="light" \| "dark"` | host owns light/dark; hides the built-in toggle |
+| `ui-font="inherit"` | match your app's font |
+| `accent="#e11d48"` | your brand color, everywhere the editor is accented; also `var(--brand)` or `inherit` |
+| `toolbar="none"` | hide the editor's own top bar |
+| `footer="none"` | drop the "Powered by SELISE Blocks © 2026" strip, or pass your own line |
+| `toolbar="undo,redo,export"` | …or keep only these parts |
+| `.storageProvider` + `.storageLimits` | image uploads to your backend |
+| `.aiProvider` | `async (prompt) => text`, powers the AI draft panel |
+| `.messages` | override any UI string |
+
+Every attribute is also a property. TypeScript declarations ship with the package. Full reference and integration recipes: **[DOCS.md](DOCS.md)**.
+
+## For AI agents
+
+Everything an assistant needs to wire this up correctly:
+
+```
+PACKAGE   @seliseblocks/mailcraft — Web Component, zero runtime deps
+IMPORT    import '@seliseblocks/mailcraft'   (side effect: registers the element)
+          Safe to import under SSR; the element itself renders in a browser only.
+TYPES     TypeScript declarations ship in the package (types/index.d.ts) for every
+          named export; 'mailcraft-editor' is registered in HTMLElementTagNameMap.
+ELEMENT   <mailcraft-editor id="editor"></mailcraft-editor>
+MOUNT     createEditor(target, options) -> handle   (no tag needed)
+          target  = CSS selector or Element; throws if it matches nothing
+          options = html, name, variables, locale, dir, theme, uiFont, accent, toolbar,
+                    footer, storageProvider, storageLimits, aiProvider, iconProvider,
+                    messages, height, replace, onChange(doc), onExport(html)
+                    name = template name for `html`; read only alongside it
+          handle  = the METHODS below + .element + .destroy()
+          The container supplies the height; the editor fills it.
+
+DATA      HTML in, HTML out. There is no JSON document format in the public API.
+          editor.loadTemplate({ name, html })   apply HTML  (undoable, deep-copied)
+          editor.importHtml(html)               apply HTML  (same importer)
+          editor.exportHtml() -> string         send-ready email HTML
+          Persist by storing exportHtml() and passing it back to loadTemplate().
+          Unclassifiable markup survives as a raw-HTML block. Nothing is dropped.
+          Condition/Loop blocks export literal {{#if expr}}/{{#each expr}} tags
+          (always balanced) for the host's templating engine; never evaluated
+          by the editor, and re-import restores them as blocks.
+
+EVENTS    'change'  detail = internal doc (do not persist this)
+          'export'  detail = HTML string
+
+ATTRS     variables="a,b,c" | locale="de" | theme="dark" | dir="rtl"
+          ui-font="inherit" | accent="#e11d48" | accent="var(--brand)"
+          toolbar="none" | toolbar="undo,redo,export" | footer="none"
+PROPS     .variables .toolbar .footer .uiFont .accent .messages .aiProvider .iconProvider
+          .storageProvider .storageLimits
+METHODS   exportHtml() importHtml(html) loadTemplate(tpl) undo() redo()
+          screenshotPng() previewScreenshot() downloadScreenshot() copyScreenshot()
+
+KEYS      Bound on window, so they survive toolbar="none":
+          Esc (leave field / deselect + close), Ctrl/Cmd+Z, Shift+Ctrl/Cmd+Z,
+          Ctrl/Cmd+E (export dialog), Ctrl/Cmd+K (link, while editing),
+          Ctrl/Cmd+D (duplicate), Backspace|Delete (delete selection).
+
+UPLOADS   Limits and a provider are both required, or every upload is refused.
+          editor.storageLimits   = { accept:['image/jpeg','image/png','image/gif'],
+                                     maxBytes: 2*1024*1024 }
+          editor.storageProvider = { list(q), upload(file, o), folders?(), remove?(a),
+                                     limits? }
+          provider.limits is merged per key under .storageLimits, and satisfies
+          the requirement on its own. With no provider the library is empty and
+          local to the draft — the package ships no files of its own.
+          The editor never talks to a backend of its own; its only fetch is the
+          screenshot capture inlining the template's own images.
+
+TOOLBAR   Parts: logo status device undo redo theme ai code preview export
+          Attribute = allow-list (keep these). Property = { part: false } (drop these).
+          none|hidden|off|false = no bar at all; all = the default.
+          Hidden undo/redo/export stay reachable — methods, plus Ctrl/Cmd+Z, +E.
+          preview, code and ai are bar-only: hiding them removes the panel.
+
+DO NOT    Do not use getContent()/setContent() — internal, shape may change.
+          Do not expect a campaign/title option — there is none; <title> is "Email".
+```
+
+## Develop
+
+```sh
+npm install && node build.js && npm test
+```
+
+`examples/vanilla.html` is a complete host page — open it directly, no server needed. It ships in the npm package too, so it is there after an install; the [hosted copy](https://mailcraft.seliseblocks.com/examples/vanilla.html) is the same file.
+
+MIT