@seliseblocks/mailcraft 0.1.0

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@seliseblocks/mailcraft",
+  "version": "0.1.0",
+  "description": "Framework-agnostic drag-and-drop email template editor, packaged as a zero-dependency Web Component.",
+  "license": "MIT",
+  "author": "SELISE Digital Platforms",
+  "homepage": "https://mailcraft.seliseblocks.com",
+  "bugs": "https://github.com/SELISEdigitalplatforms/blocks-mailcraft/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SELISEdigitalplatforms/blocks-mailcraft.git"
+  },
+  "keywords": [
+    "email",
+    "email-template",
+    "email-builder",
+    "editor",
+    "drag-and-drop",
+    "web-component",
+    "custom-element",
+    "html-email",
+    "wysiwyg",
+    "no-dependencies"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "./src/index.js",
+    "./src/mailcraft-editor.js",
+    "./dist/*"
+  ],
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "unpkg": "./dist/mailcraft-editor.bundle.js",
+  "jsdelivr": "./dist/mailcraft-editor.bundle.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./dist/*": "./dist/*",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "dist",
+    "examples",
+    "README.md",
+    "DOCS.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node build.js",
+    "test": "node test/storage.test.mjs && node test/export.test.mjs && node test/templates.test.mjs && node test/system.test.mjs && node test/toolbar.test.mjs && node test/editor-dom.test.mjs && node test/css-cascade.test.mjs && node test/render-dom.test.mjs && node test/import-html.test.mjs && node test/interaction.test.mjs && node test/focus-preserve.test.mjs && node test/shortcuts.test.mjs && node test/import-structure.test.mjs",
+    "prepublishOnly": "npm run build && npm test",
+    "coverage": "c8 --reporter=text --reporter=text-summary --src=src --all --exclude=\"test/**\" --exclude=\"examples/**\" --exclude=\"build.js\" npm test"
+  },
+  "devDependencies": {
+    "c8": "^11.0.0",
+    "esbuild": "^0.28.2",
+    "jsdom": "^25.0.1"
+  }
+}

package/src/core/accent.js

@@ -0,0 +1,194 @@
+/**
+ * Host brand color -> the editor's four accent tokens.
+ *
+ * A host that passes `accent="#e11d48"` means "make the chrome my brand",
+ * not "set one variable": `--ed-accent` alone would leave hover states on the
+ * old blue, white text sitting on a pale brand color, and the selection wash
+ * tinted the wrong hue. So one input color derives the whole set --
+ * `--ed-accent`, `--ed-accent-strong` (hover/active), `--ed-accent-ink` (what
+ * is legible *on* the accent) and `--ed-soft` (the tinted wash behind
+ * selected rows and active tabs).
+ *
+ * Two rules do the work, both contrast-driven rather than taste-driven,
+ * because the brand color arrives at runtime and nobody gets to eyeball it:
+ *
+ * 1. The accent has to stay readable against the chrome it sits on -- it is
+ *    used for text and 1px icon strokes, not just fills. A brand yellow on
+ *    the light panels, or a brand navy on the dark ones, is darkened or
+ *    lightened just far enough to clear WCAG AA (4.5:1) and no further, so a
+ *    brand that already passes is used exactly as given.
+ * 2. `--ed-accent-ink` picks white or near-black by whichever wins contrast
+ *    against the resolved accent, so a label on a filled accent button is
+ *    never the wrong one for a mid-tone brand.
+ *
+ * Deliberately DOM-free and pure: the element resolves the attribute down to
+ * a color string, this module does the color math -- which keeps the math
+ * testable without a document.
+ */
+
+/** The chrome the accent has to survive against: `--ed-panel` in each palette (render/style.js). */
+const LIGHT_BG = { r: 255, g: 255, b: 255 };
+const DARK_BG = { r: 17, g: 24, b: 39 };
+const WHITE = { r: 255, g: 255, b: 255 };
+/** Not pure black: near `--ed-text`, so accent buttons don't read harsher than the rest of the UI. */
+const NEAR_BLACK = { r: 11, g: 17, b: 32 };
+
+/** WCAG AA for normal text. The accent renders as 11-12px labels and hairline icon strokes, so AA is the floor, not a nicety. */
+const MIN_CONTRAST = 4.5;
+
+const clamp255 = (n) => Math.max(0, Math.min(255, Math.round(n)));
+
+/** sRGB channel -> linear light, per WCAG's relative-luminance definition. */
+function toLinear(channel) {
+  const c = channel / 255;
+  return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+
+function luminance(c) {
+  return 0.2126 * toLinear(c.r) + 0.7152 * toLinear(c.g) + 0.0722 * toLinear(c.b);
+}
+
+/** WCAG contrast ratio, 1 (identical) to 21 (black on white). */
+export function contrast(a, b) {
+  const l1 = luminance(a);
+  const l2 = luminance(b);
+  return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
+}
+
+/** Linear blend, `t` = how far from `a` toward `b`. */
+function mix(a, b, t) {
+  return {
+    r: clamp255(a.r + (b.r - a.r) * t),
+    g: clamp255(a.g + (b.g - a.g) * t),
+    b: clamp255(a.b + (b.b - a.b) * t),
+  };
+}
+
+export const toHex = (c) => '#' + [c.r, c.g, c.b].map((n) => clamp255(n).toString(16).padStart(2, '0')).join('');
+
+const rgba = (c, alpha) => `rgba(${clamp255(c.r)},${clamp255(c.g)},${clamp255(c.b)},${alpha})`;
+
+/** `hue` in degrees, `s`/`l` as 0..1. Mirrors the CSS hsl() definition so `hsl(340 82% 52%)` lands where a browser would put it. */
+function hslToRgb(hue, s, l) {
+  const h = (((hue % 360) + 360) % 360) / 60;
+  const c = (1 - Math.abs(2 * l - 1)) * s;
+  const x = c * (1 - Math.abs((h % 2) - 1));
+  const m = l - c / 2;
+  const [r, g, b] = h < 1 ? [c, x, 0] : h < 2 ? [x, c, 0] : h < 3 ? [0, c, x]
+    : h < 4 ? [0, x, c] : h < 5 ? [x, 0, c] : [c, 0, x];
+  return { r: clamp255((r + m) * 255), g: clamp255((g + m) * 255), b: clamp255((b + m) * 255) };
+}
+
+/**
+ * Parses the color notations a host actually types into an attribute --
+ * `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()/rgba()` and `hsl()/hsla()`,
+ * comma- or space-separated, with or without `%`. Alpha parses but is
+ * dropped: the accent is a solid color, and `--ed-soft` owns the translucent
+ * tint. Named CSS colors are not resolved here (that needs a browser); the
+ * element falls back to a DOM probe for those.
+ *
+ * @returns {{r:number,g:number,b:number}|null} null when it isn't a color.
+ */
+export function parseColor(value) {
+  const raw = String(value == null ? '' : value).trim().toLowerCase();
+  if (!raw) return null;
+
+  const hex = /^#([0-9a-f]{3,8})$/.exec(raw);
+  if (hex) {
+    const h = hex[1];
+    if (h.length === 3 || h.length === 4) {
+      return { r: parseInt(h[0] + h[0], 16), g: parseInt(h[1] + h[1], 16), b: parseInt(h[2] + h[2], 16) };
+    }
+    if (h.length === 6 || h.length === 8) {
+      return { r: parseInt(h.slice(0, 2), 16), g: parseInt(h.slice(2, 4), 16), b: parseInt(h.slice(4, 6), 16) };
+    }
+    return null;
+  }
+
+  const fn = /^(rgba?|hsla?)\(([^)]*)\)$/.exec(raw);
+  if (!fn) return null;
+  const parts = fn[2].replace(/\//g, ' ').split(/[\s,]+/).filter(Boolean);
+  if (parts.length < 3) return null;
+  const num = (s) => parseFloat(s);
+  let out;
+  if (fn[1].startsWith('rgb')) {
+    const chan = (s) => (s.endsWith('%') ? (num(s) / 100) * 255 : num(s));
+    out = { r: clamp255(chan(parts[0])), g: clamp255(chan(parts[1])), b: clamp255(chan(parts[2])) };
+  } else {
+    const pct = (v) => (v.endsWith('%') ? num(v) / 100 : num(v));
+    const unit = (v) => Math.max(0, Math.min(1, pct(v)));
+    out = hslToRgb(num(parts[0]), unit(parts[1]), unit(parts[2]));
+  }
+  return Number.isNaN(out.r + out.g + out.b) ? null : out;
+}
+
+/**
+ * Walks the color toward black (light chrome) or white (dark chrome) until it
+ * clears `MIN_CONTRAST` against the panel behind it. Steps are small and it
+ * stops at the first passing one, so a brand color that already has enough
+ * contrast comes back untouched -- the goal is legibility, not repainting
+ * someone's brand.
+ */
+function fitContrast(color, bg) {
+  const toward = luminance(bg) > 0.5 ? NEAR_BLACK : WHITE;
+  let out = color;
+  for (let step = 1; step <= 20 && contrast(out, bg) < MIN_CONTRAST; step += 1) {
+    out = mix(color, toward, step / 20);
+  }
+  return out;
+}
+
+/** White or near-black, whichever is legible on `bg`. */
+const inkFor = (bg) => (contrast(bg, WHITE) >= contrast(bg, NEAR_BLACK) ? WHITE : NEAR_BLACK);
+
+/**
+ * Every accent token, for one brand color in one chrome.
+ *
+ * Two families, because the editor paints on two surfaces:
+ *
+ *   --ed-accent*   panel chrome (header, inspector, tabs, sliders), which
+ *                  follows the light/dark theme.
+ *   --ed-accent-sheet*  everything drawn *on the email sheet* -- the row grip,
+ *                  the block toolbars, the drop outlines. The sheet is a white
+ *                  page in both themes, so these are always fitted against
+ *                  white; a dark-theme accent light enough to read on the dark
+ *                  panels would disappear on the page.
+ *
+ * `strong` moves *away* from the surface (darker on light, lighter on dark) so
+ * hover always reads as "more", the way both built-in palettes behave.
+ *
+ * @param {{r:number,g:number,b:number}} color  parsed brand color
+ * @param {string} chrome                       'light' | 'dark'
+ * @returns {Object} token name -> CSS value
+ */
+export function accentTokens(color, chrome) {
+  const dark = chrome === 'dark';
+  const base = fitContrast(color, dark ? DARK_BG : LIGHT_BG);
+  const strong = dark ? mix(base, WHITE, 0.22) : mix(base, NEAR_BLACK, 0.2);
+  // In light chrome the panel *is* white, so the two families coincide and
+  // this costs nothing.
+  const sheet = dark ? fitContrast(color, LIGHT_BG) : base;
+  return {
+    '--ed-accent': toHex(base),
+    '--ed-accent-strong': toHex(strong),
+    '--ed-accent-ink': toHex(inkFor(base)),
+    // The lighter stop of the brand mark's gradient -- a highlight, so it
+    // moves toward white regardless of chrome.
+    '--ed-accent-tint': toHex(mix(base, WHITE, 0.34)),
+    // The same alphas the built-in palettes use -- a wash has to stay a hint
+    // of color over its surface, not a second surface.
+    '--ed-soft': rgba(base, dark ? 0.13 : 0.09),
+    '--ed-glow': rgba(base, 0.28),
+    // Text selection: heavier than a wash (it has to be visible under type)
+    // and heavier still on dark, where the same alpha reads fainter.
+    '--ed-select': rgba(base, dark ? 0.3 : 0.22),
+    '--ed-accent-sheet': toHex(sheet),
+    '--ed-accent-sheet-strong': toHex(mix(sheet, NEAR_BLACK, 0.22)),
+    '--ed-accent-sheet-ink': toHex(inkFor(sheet)),
+    // Drop-target dashes and hairlines on the page.
+    '--ed-accent-sheet-line': rgba(sheet, 0.5),
+  };
+}
+
+/** The tokens this module owns, so the element can clear exactly what it set when `accent` goes away. */
+export const ACCENT_VARS = Object.keys(accentTokens({ r: 0, g: 0, b: 0 }, 'light'));

package/src/core/assets.js

@@ -0,0 +1,15 @@
+import { uid } from './ids.js';
+import { PH } from './placeholder.js';
+
+export const FOLDERS = ['All files', 'Brand', 'Product', 'Photography', 'Uploads'];
+
+export const seedAssets = () => [
+  { id: uid(), name: 'logo-lockup.png', url: PH('logo lockup', 480, 180), folder: 'Brand', w: 480, ht: 180, size: 18400 },
+  { id: uid(), name: 'hero-workshop.jpg', url: PH('workshop hero', 600, 340), folder: 'Photography', w: 600, ht: 340, size: 142000 },
+  { id: uid(), name: 'jacket-03-front.jpg', url: PH('jacket 03 front', 520, 360), folder: 'Product', w: 520, ht: 360, size: 98000 },
+  { id: uid(), name: 'jacket-03-detail.jpg', url: PH('jacket 03 detail', 520, 360), folder: 'Product', w: 520, ht: 360, size: 91000 },
+  { id: uid(), name: 'boots-pair.jpg', url: PH('boots pair', 520, 360), folder: 'Product', w: 520, ht: 360, size: 88000 },
+  { id: uid(), name: 'texture-waxed.jpg', url: PH('waxed texture', 600, 240), folder: 'Photography', w: 600, ht: 240, size: 64000 },
+];
+
+export const KB = (n) => (n > 1048576 ? (n / 1048576).toFixed(1) + ' MB' : Math.round(n / 1024) + ' KB');

package/src/core/binder.js

@@ -0,0 +1,119 @@
+/** Ported verbatim from the original `binder(getProps, set)` and `decorate(list)`. Pure field-descriptor logic, no DOM. */
+export function binder(getProps, set, core) {
+  return {
+    head: (label) => ({ kind: 'head', label }),
+    text: (label, key, ph) => ({ kind: 'text', label, value: getProps()[key] ?? '', placeholder: ph || '', onChange: (v) => set(key, v) }),
+    area: (label, key, ph) => ({ kind: 'area', label, value: getProps()[key] ?? '', placeholder: ph || '', onChange: (v) => set(key, v) }),
+    // Live typing only commits parseable numbers -- `Number('')` is 0, and
+    // committing that the instant a field was cleared to retype (e.g. the
+    // theme's content width collapsing to 0px mid-edit) was one of the
+    // "inputs behave weird" symptoms. Blur settles the final value, clamped.
+    num: (label, key, min, max) => ({
+      kind: 'num', label, value: getProps()[key] ?? 0, min, max,
+      onChange: (v) => { const n = parseFloat(v); if (Number.isFinite(n)) set(key, n); },
+      onBlur: (v) => {
+        if (core && core.rendering) return;
+        const n = parseFloat(v);
+        set(key, Math.min(max, Math.max(min, Number.isFinite(n) ? n : (getProps()[key] ?? min))));
+      },
+    }),
+    color: (label, key) => ({ kind: 'color', label, value: getProps()[key] ?? '', swatch: /^#/.test(getProps()[key] || '') ? getProps()[key] : '#ffffff', onChange: (v) => set(key, v) }),
+    // A native range slider commits on every drag tick -- dozens a second --
+    // and each one used to trigger a full doc clone + re-render (see
+    // `commit`), which is what made dragging feel like stutter instead of a
+    // smooth slide. A stepper sidesteps that class of bug entirely: +/- is a
+    // single discrete commit per click, and typing a value only commits once
+    // you're done (on blur), not per keystroke.
+    range: (label, key, min, max, step, unit) => {
+      const cur = getProps()[key] ?? min;
+      const s = step || 1;
+      const decimals = (String(s).split('.')[1] || '').length;
+      const clamp = (v) => Math.min(max, Math.max(min, v));
+      const round = (v) => Number(v.toFixed(decimals));
+      const commit = (v) => set(key, round(clamp(v)));
+      return {
+        kind: 'range', label, value: cur, min, max, step: s, unit: unit || '', display: cur + (unit || ''),
+        onDec: () => commit(cur - s),
+        onInc: () => commit(cur + s),
+        // Live-typed digits aren't clamped (typing "1" toward "12" with a min
+        // of 10 would otherwise get snapped back to 10 mid-keystroke, making
+        // the second digit impossible to enter) -- only guarded against a
+        // non-numeric intermediate state (e.g. a bare "-").
+        onInput: (v) => { const n = parseFloat(v); if (!Number.isNaN(n)) set(key, n); },
+        // A render tears down and rebuilds the whole panel subtree (no
+        // diffing); removing this still-focused input as part of that forces
+        // a synchronous, spurious `blur` before the rebuilt replacement can
+        // be refocused. Committing on that blur re-renders again, which
+        // tears down and blurs again -- an infinite loop. `core.rendering`
+        // (set for the render()'s duration) tells a real blur apart from
+        // that artifact -- same guard as canvas.js's RTE `onBlur`.
+        onBlur: (v) => { if (core && core.rendering) return; const n = parseFloat(v); commit(Number.isNaN(n) ? cur : n); },
+      };
+    },
+    // A real drag slider, for coarse visual sizing (content width). The
+    // per-tick commit problem that ruled sliders out for ordinary fields
+    // (see `range` above) is sidestepped by contract: the renderer moves the
+    // value bubble live during the drag but only calls `onCommit` on release
+    // ('change'), so a whole drag costs one re-render.
+    slider: (label, key, min, max, step, unit) => ({
+      kind: 'slider', label, value: getProps()[key] ?? min, min, max, step: step || 1, unit: unit || '',
+      onCommit: (v) => { const n = parseFloat(v); if (Number.isFinite(n)) set(key, Math.min(max, Math.max(min, n))); },
+    }),
+    sel: (label, key, opts) => {
+      const options = opts.map((o) => (typeof o === 'string' ? { value: o, label: o } : o));
+      const current = getProps()[key];
+      return {
+        kind: 'select', label,
+        // New controls must not render as an unexplained blank on documents
+        // saved before that property existed. The renderer already uses the
+        // first option as its semantic fallback; show that same choice here.
+        value: current == null ? (options[0]?.value ?? '') : current,
+        options,
+        onChange: (v) => set(key, v),
+      };
+    },
+    seg: (label, key, opts) => ({
+      kind: 'seg', label, options: opts.map((o) => {
+        const v = typeof o === 'string' ? o : o.value; const l = typeof o === 'string' ? o : o.label;
+        const on = getProps()[key] === v;
+        return { label: l, bg: on ? 'var(--ed-accent)' : 'transparent', fg: on ? 'var(--ed-accent-ink)' : 'var(--ed-muted)', onClick: () => set(key, v) };
+      }),
+    }),
+    tog: (label, key, defaultOn) => {
+      const raw = getProps()[key];
+      const on = raw === undefined ? !!defaultOn : !!raw;
+      return { kind: 'toggle', label, on, onChange: () => set(key, !on) };
+    },
+    btn: (label, onClick) => ({ kind: 'btn', label, onClick }),
+  };
+}
+
+/**
+ * A grid of linked steppers for props that come in sides/corners ("Space
+ * inside" top/bottom/left/right). `toggle` ({on, onChange}), when present,
+ * renders as the header's "More options" switch that swaps the linked pair
+ * for per-side fields; `label: null` drops the header row entirely (the
+ * section head above already names the group).
+ */
+export function group(label, items, toggle) {
+  return { kind: 'rangeGroup', label, items, toggle: toggle || null };
+}
+
+export function decorate(list) {
+  return list.filter(Boolean).map((f, i) => {
+    const d = Object.assign({}, f, {
+      key: i,
+      isHead: f.kind === 'head', isArea: f.kind === 'area', isBtn: f.kind === 'btn', isSeg: f.kind === 'seg',
+      isRange: f.kind === 'range', isToggle: f.kind === 'toggle', isSocial: f.kind === 'social', isTableGrid: f.kind === 'tablegrid', isRichLinks: f.kind === 'richLinks',
+      isRangeGroup: f.kind === 'rangeGroup', isSlider: f.kind === 'slider',
+      isRow: ['text', 'num', 'color', 'select'].indexOf(f.kind) > -1,
+      isField: ['text', 'num', 'color', 'select'].indexOf(f.kind) > -1,
+      isText: f.kind === 'text', isNum: f.kind === 'num', isColor: f.kind === 'color', isSelect: f.kind === 'select',
+    });
+    // Group items are ranges rendered as grid cells: they need decorated
+    // flags and focus keys of their own, namespaced under the group's index
+    // so they stay unique against the flat list.
+    if (d.isRangeGroup) d.items = f.items.map((it, j) => Object.assign({}, it, { key: i + 'g' + j, isRange: true }));
+    return d;
+  });
+}

package/src/core/blocks.js

@@ -0,0 +1,256 @@
+import { uid } from './ids.js';
+import { PH } from './placeholder.js';
+import { THEME } from './theme.js';
+
+export const BLOCKS = [
+  { type: 'text', code: 'TXT', label: 'Text', hint: 'Rich text — edit inline', make: () => ({ html: 'Hi {{ first_name }} — we cut three things from the fall line and kept the two that mattered. Here they are.', size: 16, lh: 1.6, color: '', align: 'left', weight: '400', py: 10, px: 0 }) },
+  { type: 'image', code: 'IMG', label: 'Image', hint: 'Image from the library', make: () => ({ src: PH('hero image 600 × 320', 600, 320), alt: 'Hero image', width: 100, align: 'center', href: '', radius: 10, py: 0, px: 0 }) },
+  { type: 'button', code: 'BTN', label: 'Button', hint: 'Call to action', make: () => ({ label: 'Shop the drop', href: 'https://example.com', bg: '#0065b3', color: '#ffffff', radius: 8, py: 13, px: 26, align: 'left', size: 15, full: false, borderW: 0, borderStyle: 'solid', borderColor: '' }) },
+  { type: 'divider', code: 'DIV', label: 'Divider', hint: 'Horizontal rule', make: () => ({ thickness: 1, lineStyle: 'solid', color: '#e2e8f0', width: 100, py: 14 }) },
+  { type: 'spacer', code: 'SPC', label: 'Spacer', hint: 'Vertical space', make: () => ({ height: 32 }) },
+  { type: 'social', code: 'SOC', label: 'Social', hint: 'Social icon row', make: () => ({ items: 'Instagram|https://instagram.com\nX|https://x.com\nLinkedIn|https://linkedin.com\nYouTube|https://youtube.com', align: 'center', size: 20, gap: 12, color: '#0065b3', palette: 'custom', shape: 'outline', showLabel: false }) },
+  { type: 'video', code: 'VID', label: 'Video', hint: 'Thumbnail + play badge', make: () => ({ src: PH('video thumbnail 600 × 330', 600, 330), href: 'https://example.com/watch', caption: 'Two minutes inside the workshop', badge: '#172033' }) },
+  { type: 'html', code: 'HTM', label: 'HTML', hint: 'Raw HTML block', make: () => ({ code: '<p style="font:13px/1.6 ui-monospace,monospace;margin:0">&lt;!-- raw HTML passes through untouched --&gt;</p>' }) },
+  { type: 'countdown', code: 'CDN', label: 'Countdown', hint: 'Live countdown', make: () => ({ target: new Date(Date.now() + 2.4 * 86400000).toISOString().slice(0, 16), label: 'Subscriber pricing ends in', color: '#172033' }) },
+  { type: 'menu', code: 'NAV', label: 'Menu', hint: 'Navigation row', make: () => ({ items: 'New in|https://example.com/new\nOuterwear|https://example.com/outerwear\nArchive|https://example.com/archive', align: 'center', size: 12, gap: 20, color: '#172033' }) },
+];
+BLOCKS.push(
+  { type: 'heading', code: 'HED', label: 'Heading', hint: 'Display heading', make: () => ({ text: 'What we kept', level: 'h2', size: 34, lh: 1.12, align: 'left', color: '', weight: '600', font: 'body', py: 8, px: 0 }) },
+  { type: 'list', code: 'LST', label: 'List', hint: 'Bulleted or numbered list', make: () => ({ items: 'Import your list\nPick a template\nSend the first one', ordered: false, size: 15, lh: 1.7, color: '', gap: 4, py: 8, px: 0 }) },
+  { type: 'table', code: 'TBL', label: 'Table', hint: 'Data table — edit cells inline', make: () => ({ data: 'Plan|Price|Seats\nStarter|$19|3\nTeam|$49|10\nStudio|$99|25', header: true, borders: true, borderWidth: 1, borderStyle: 'solid', striped: true, pad: 10, size: 14, headBg: '#f8fafc', lineColor: '#e2e8f0', align: 'left', width: 100 }) },
+  { type: 'embed', code: 'EMB', label: 'Embed', hint: 'Iframe embed — map, form, player', make: () => ({ src: 'https://example.com/embed', height: 320, label: 'Embedded content', py: 8 }) },
+  { type: 'css', code: 'CSS', label: 'Raw CSS', hint: 'Inject a style block', make: () => ({ code: '.mc-note { font: 13px/1.6 "Helvetica Neue", Helvetica, Arial, sans-serif; color: #0065b3; letter-spacing: 0.04em; }', note: 'Styles apply to raw HTML blocks below.' }) },
+  { type: 'codeblock', code: 'PRE', label: 'Code', hint: 'Preformatted code sample', make: () => ({ code: 'curl -X POST https://api.example.com/v1/sends \\\n  -H "Authorization: Bearer $KEY" \\\n  -d campaign=mc-4471', bg: '#172033', color: '#e8e9ea', size: 12.5, pad: 14 }) },
+);
+BLOCKS.push(
+  { type: 'box', code: 'BOX', label: 'Section box', hint: 'Styled container with free content', make: () => ({ html: '<strong style="font-size:19px;display:block;margin-bottom:6px">Section title</strong>Drop copy here, or paste markup. The box takes background, padding, border and radius.', bg: '#f8fafc', bgImage: '', border: 1, borderStyle: 'solid', lineColor: '#e2e8f0', topBorder: true, rightBorder: true, bottomBorder: true, leftBorder: true, radius: 12, pad: 22, align: 'left', minH: 0, maxW: 100, shadow: false }) },
+  { type: 'svg', code: 'SVG', label: 'Inline SVG', hint: 'Paste SVG markup', make: () => ({ code: '<svg viewBox="0 0 120 40" width="120" height="40" fill="none" stroke="#0065b3" stroke-width="1.5"><rect x="0.75" y="0.75" width="118.5" height="38.5"/><path d="M12 28l14-16 12 10 10-8 18 14"/></svg>', align: 'left', width: 100, py: 10 }) },
+);
+
+export const DEF = (t) => BLOCKS.find((b) => b.type === t);
+export const mk = (t) => ({ id: uid(), type: t, props: DEF(t).make() });
+export const blk = (type, over) => { const b = mk(type); Object.assign(b.props, over || {}); return b; };
+
+export const LAYOUTS = [
+  { spans: [100], label: '1 col' },
+  { spans: [50, 50], label: '50 / 50' },
+  { spans: [33, 67], label: '33 / 67' },
+  { spans: [67, 33], label: '67 / 33' },
+  { spans: [33, 34, 33], label: '3 col' },
+  { spans: [25, 25, 25, 25], label: '4 col' },
+];
+
+export const mkRow = (spans, blocks) => ({
+  id: uid(),
+  props: {
+    bg: '', bgImage: '', bgSize: 'cover', bgPos: 'center', bgRepeat: 'no-repeat', overlay: 0,
+    border: 0, borderStyle: 'solid', lineColor: '#e2e2e5', bTop: true, bRight: true, bBottom: true, bLeft: true, radius: 0, shadow: '', maxW: 100,
+    mt: 0, mr: 0, mb: 0, ml: 0,
+    layout: 'columns', flexDir: 'row', justify: 'flex-start', alignItems: 'stretch', wrap: true, gridCols: 2,
+    py: 20, px: 24, padSplit: false, gap: 20, valign: 'top', stackMobile: true,
+  },
+  cols: spans.map((s, i) => ({ id: uid(), span: s, blocks: i === 0 && blocks ? blocks : [] })),
+});
+
+export const groupRows = (id) => (GROUPS[id] ? GROUPS[id].build() : []);
+
+/** Compound presets: `build()` returns full row(s) built from ordinary blocks -- once inserted, a group is indistinguishable from any other row/blocks (no groupId persists), so every part stays individually selectable and editable. */
+export const GROUPS = {
+  hero: {
+    label: 'Hero', icon: 'hero',
+    build: () => {
+      const row = mkRow([100]);
+      Object.assign(row.props, { py: 56, px: 36, bgImage: PH('hero background 1200 × 560', 1200, 560), overlay: 46, gap: 0 });
+      row.cols[0].blocks = [
+        blk('text', { html: 'AUTUMN 2026', size: 11, align: 'center', color: '#ffffff', py: 0 }),
+        blk('heading', { text: 'Built for the long haul', size: 44, align: 'center', color: '#ffffff', py: 10 }),
+        blk('text', { html: 'Waxed cotton, storm cuffs, and a repair promise that outlives the season.', size: 15, align: 'center', color: '#ffffff', py: 4 }),
+        blk('button', { label: 'Shop the drop', align: 'center', bg: '#ffffff', color: '#172033', radius: 8 }),
+      ];
+      return [row];
+    },
+  },
+  card: {
+    label: 'Card', icon: 'card',
+    build: () => {
+      const row = mkRow([100]);
+      Object.assign(row.props, { bg: '#f8fafc', border: 1, lineColor: '#e2e8f0', radius: 12, py: 0, px: 0, gap: 0 });
+      row.cols[0].blocks = [
+        blk('image', { src: PH('card image 520 × 300', 520, 300), alt: 'Inside the workshop', py: 0, px: 0 }),
+        blk('heading', { text: 'Inside the workshop', size: 22, py: 16, px: 20 }),
+        blk('text', { html: 'Three benches, two machines, and a rule about finishing what you start.', size: 13.5, py: 0, px: 20 }),
+        blk('button', { label: 'Read the story', bg: '#0065b3', color: '#ffffff', size: 13, py: 10, px: 18, align: 'left' }),
+      ];
+      return [row];
+    },
+  },
+  product: {
+    label: 'Product', icon: 'product',
+    build: () => {
+      const row = mkRow([45, 55]);
+      Object.assign(row.props, { valign: 'middle', py: 16 });
+      row.cols[0].blocks = [blk('image', { src: PH('product shot 520 × 520', 520, 520), alt: 'Field Jacket 03', py: 0, px: 0 })];
+      row.cols[1].blocks = [
+        blk('heading', { text: 'Field Jacket 03', size: 26, py: 0 }),
+        blk('text', { html: '<strong>$248</strong> — waxed cotton, storm cuffs, cut and sewn in Portugal.', size: 14, py: 8 }),
+        blk('button', { label: 'View product' }),
+      ];
+      return [row];
+    },
+  },
+  stats: {
+    label: 'Stats', icon: 'stats',
+    build: () => {
+      const row = mkRow([33, 34, 33]);
+      Object.assign(row.props, { py: 22, gap: 8 });
+      [['12k', 'Subscribers'], ['41%', 'Open rate'], ['8.2%', 'Click rate']].forEach((pair, i) => {
+        row.cols[i].blocks = [
+          blk('heading', { text: pair[0], size: 32, align: 'center', color: '#0065b3', py: 0 }),
+          blk('text', { html: pair[1].toUpperCase(), size: 11, align: 'center', py: 4 }),
+        ];
+      });
+      return [row];
+    },
+  },
+  quote: {
+    label: 'Quote', icon: 'quote',
+    build: () => {
+      const row = mkRow([100]);
+      Object.assign(row.props, { py: 18, gap: 0 });
+      row.cols[0].blocks = [
+        blk('text', { html: '<em>“It shipped in a week and nobody asked me for a spec.”</em>', size: 19, lh: 1.45, py: 0 }),
+        blk('text', { html: 'RAE OKONKWO, FOUNDRY SUPPLY', size: 11, py: 6 }),
+      ];
+      return [row];
+    },
+  },
+  gallery: {
+    label: 'Gallery', icon: 'gallery',
+    build: () => {
+      const row = mkRow([50, 50]);
+      Object.assign(row.props, { py: 10, gap: 10 });
+      row.cols[0].blocks = [
+        blk('image', { src: PH('image 01', 400, 300), alt: '', py: 0, px: 0 }),
+        blk('image', { src: PH('image 03', 400, 300), alt: '', py: 10, px: 0 }),
+      ];
+      row.cols[1].blocks = [
+        blk('image', { src: PH('image 02', 400, 300), alt: '', py: 0, px: 0 }),
+        blk('image', { src: PH('image 04', 400, 300), alt: '', py: 10, px: 0 }),
+      ];
+      return [row];
+    },
+  },
+  footer: {
+    label: 'Footer', icon: 'footer',
+    build: () => {
+      const row = mkRow([100]);
+      Object.assign(row.props, { py: 22, gap: 0 });
+      row.cols[0].blocks = [
+        blk('divider', { py: 0 }),
+        blk('social', { align: 'center', size: 18, shape: 'bare' }),
+        blk('text', { html: '<strong>MailCraft, Inc.</strong><br />220 Foundry Street, Suite 4, Portland OR 97209<br />You are receiving this because you signed up at mailcraft.co.', size: 11.5, align: 'center', py: 6 }),
+        blk('text', { html: '<a href="{{ unsubscribe_url }}">Unsubscribe</a> · <a href="#">Update preferences</a>', size: 11.5, align: 'center', py: 0 }),
+      ];
+      return [row];
+    },
+  },
+};
+
+export const PALETTE = [
+  { t: 'heading' }, { t: 'text' }, { t: 'list' }, { g: 'quote' }, { t: 'image' }, { g: 'gallery' },
+  { t: 'button' }, { t: 'table' }, { g: 'card' }, { g: 'product' }, { g: 'hero' }, { g: 'stats' },
+  { t: 'box' }, { t: 'divider' }, { t: 'spacer' }, { t: 'social' }, { t: 'video' },
+  { t: 'embed' }, { t: 'menu' }, { g: 'footer' }, { t: 'html' }, { t: 'css' }, { t: 'svg' },
+  { t: 'codeblock' }, { t: 'countdown' },
+];
+
+/**
+ * The document a fresh editor opens on: one empty row, default theme.
+ *
+ * Deliberately not a sample template. Template galleries belong to the host's
+ * own UI (pushed in via `editor.loadTemplate`), so booting into a built-in
+ * marketing layout would both pull a template catalogue into every bundle and
+ * put content in a host's editor that they never chose.
+ */
+export const blankDoc = () => ({ theme: THEME(), rows: [mkRow([100])] });
+
+export function migrateDoc(doc) {
+  const defaults = mkRow([100]).props;
+  const emptied = [];
+  (doc.rows || []).forEach((r) => {
+    const hadBlocks = r.cols.some((c) => c.blocks.length);
+    // Outside spacing used to be one vertical `my` value. Seed the complete
+    // four-side model before defaults are applied so old documents keep their
+    // top/bottom spacing and gain neutral left/right values.
+    const legacyMarginY = r.props.my ?? 0;
+    if (r.props.mt === undefined) r.props.mt = legacyMarginY;
+    if (r.props.mr === undefined) r.props.mr = 0;
+    if (r.props.mb === undefined) r.props.mb = legacyMarginY;
+    if (r.props.ml === undefined) r.props.ml = 0;
+    r.cols.forEach((c) => {
+      // A block whose type this build no longer knows is dropped rather than
+      // rendered as an unrecognized shape; a row emptied that way goes with it.
+      c.blocks = c.blocks.filter((b) => DEF(b.type));
+      // `social.shape` used to have a 'solid' value meaning "filled badge, no
+      // particular shape" -- now that shape is split into 'circle'/'square'
+      // badges, an old 'solid' document reads as the (arbitrary but stable)
+      // 'square' choice rather than silently becoming an unrecognized value.
+      c.blocks.forEach((b) => { if (b.type === 'social' && b.props.shape === 'solid') b.props.shape = 'square'; });
+    });
+    Object.keys(defaults).forEach((k) => { if (r.props[k] === undefined) r.props[k] = defaults[k]; });
+    if (hadBlocks && !r.cols.some((c) => c.blocks.length)) emptied.push(r.id);
+  });
+  doc.rows = (doc.rows || []).filter((r) => emptied.indexOf(r.id) < 0);
+  return doc;
+}
+
+/**
+ * Any plausible document -> a complete, renderable one.
+ *
+ * The HTML path already works this way: `parseHtmlSource` classifies what it
+ * can and wraps the rest in a raw-html row rather than dropping it, so no
+ * source is ever rejected outright. JSON now gets the same contract. A partial
+ * document -- hand-written, generated by a backend, or saved by an older
+ * version -- is filled in rather than handed to the renderer with a hole in it.
+ *
+ * Everything the renderer indexes into is seeded: the six theme keys (an empty
+ * `theme` used to throw on `theme.font.replace` at export time), every row
+ * prop, at least one column per row, per-type block props from
+ * `DEF(type).make()`, and ids -- a document written by hand has none, and rows
+ * and blocks are addressed by id everywhere in the editor.
+ *
+ * Blocks of a type this build no longer knows are kept here and left to
+ * `migrateDoc`, which converts the legacy ones and drops the rest; filtering
+ * them out first would lose the conversions.
+ *
+ * Returns null when there is nothing usable, so a caller can no-op instead of
+ * replacing the user's document with an empty one.
+ */
+export function normalizeDoc(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  const rowDefaults = mkRow([100]).props;
+  const rows = (Array.isArray(input.rows) ? input.rows : []).filter((r) => r && typeof r === 'object');
+  const doc = {
+    theme: Object.assign(THEME(), input.theme || {}),
+    rows: rows.map((r) => {
+      const raw = Array.isArray(r.cols) && r.cols.length ? r.cols.filter((c) => c && typeof c === 'object') : [{}];
+      const cols = raw.length ? raw : [{}];
+      const evenSpan = Math.round(100 / cols.length);
+      return {
+        id: r.id || uid(),
+        props: Object.assign({}, rowDefaults, r.props || {}),
+        cols: cols.map((c) => ({
+          id: c.id || uid(),
+          span: Number(c.span) > 0 ? Number(c.span) : evenSpan,
+          blocks: (Array.isArray(c.blocks) ? c.blocks : []).filter((b) => b && typeof b === 'object' && b.type).map((b) => (
+            DEF(b.type)
+              ? { id: b.id || uid(), type: b.type, props: Object.assign(DEF(b.type).make(), b.props || {}) }
+              : { id: b.id || uid(), type: b.type, props: b.props || {} }
+          )),
+        })),
+      };
+    }),
+  };
+  if (!doc.rows.length) return null;
+  return migrateDoc(doc);
+}