@seliseblocks/mailcraft 0.2.14 → 0.2.16

package/src/core/parse.js

@@ -1,10 +1,10 @@
-export function parseItems(s) {
-  return String(s || '').split('\n').map((l) => l.trim()).filter(Boolean).map((l) => {
-    const i = l.indexOf('|');
-    return i < 0 ? { label: l, href: '#' } : { label: l.slice(0, i).trim(), href: l.slice(i + 1).trim() };
-  });
-}
-
-export function cellsOf(p) {
-  return String(p.data || '').split('\n').filter((l) => l.trim()).map((l) => l.split('|').map((c) => c.trim()));
-}
+export function parseItems(s) {
+  return String(s || '').split('\n').map((l) => l.trim()).filter(Boolean).map((l) => {
+    const i = l.indexOf('|');
+    return i < 0 ? { label: l, href: '#' } : { label: l.slice(0, i).trim(), href: l.slice(i + 1).trim() };
+  });
+}
+
+export function cellsOf(p) {
+  return String(p.data || '').split('\n').filter((l) => l.trim()).map((l) => l.split('|').map((c) => c.trim()));
+}

package/src/core/placeholder.js

@@ -1,15 +1,15 @@
-/** Data-URI placeholder image generator, ported verbatim from the original. */
-function enc(s) {
-  return encodeURIComponent(s).replace(/\(/g, '%28').replace(/\)/g, '%29');
-}
-
-export function PH(label, w, ht) {
-  return 'data:image/svg+xml;utf8,' + enc(
-    '<svg xmlns="http://www.w3.org/2000/svg" width="' + w + '" height="' + ht + '">' +
-    '<defs><pattern id="s" width="9" height="9" patternTransform="rotate(45)" patternUnits="userSpaceOnUse">' +
-    '<rect width="9" height="9" fill="#ececed"/><line x1="0" y1="0" x2="0" y2="9" stroke="#cfd3d8" stroke-width="3"/></pattern></defs>' +
-    '<rect width="100%" height="100%" fill="url(#s)"/>' +
-    '<rect x="0.5" y="0.5" width="' + (w - 1) + '" height="' + (ht - 1) + '" fill="none" stroke="#9aa2ab"/>' +
-    '<text x="50%" y="50%" dy="4" text-anchor="middle" font-family="ui-monospace,monospace" font-size="' + Math.max(11, Math.round(w / 40)) + '" fill="#5b6672">' + label + '</text></svg>',
-  );
-}
+/** Data-URI placeholder image generator, ported verbatim from the original. */
+function enc(s) {
+  return encodeURIComponent(s).replace(/\(/g, '%28').replace(/\)/g, '%29');
+}
+
+export function PH(label, w, ht) {
+  return 'data:image/svg+xml;utf8,' + enc(
+    '<svg xmlns="http://www.w3.org/2000/svg" width="' + w + '" height="' + ht + '">' +
+    '<defs><pattern id="s" width="9" height="9" patternTransform="rotate(45)" patternUnits="userSpaceOnUse">' +
+    '<rect width="9" height="9" fill="#ececed"/><line x1="0" y1="0" x2="0" y2="9" stroke="#cfd3d8" stroke-width="3"/></pattern></defs>' +
+    '<rect width="100%" height="100%" fill="url(#s)"/>' +
+    '<rect x="0.5" y="0.5" width="' + (w - 1) + '" height="' + (ht - 1) + '" fill="none" stroke="#9aa2ab"/>' +
+    '<text x="50%" y="50%" dy="4" text-anchor="middle" font-family="ui-monospace,monospace" font-size="' + Math.max(11, Math.round(w / 40)) + '" fill="#5b6672">' + label + '</text></svg>',
+  );
+}

package/src/core/variables.js

@@ -1,11 +1,11 @@
-export const DEFAULT_VARS = 'first_name\nlast_name\nemail\ncompany\ncity\norder_id\nplan\ndiscount\nunsubscribe_url';
-export const TOKEN = (t) => '{' + '{ ' + t + ' }' + '}';
-
-/** Variables are supplied by the host application -- the editor only ever shows the tokens, never a substituted value. */
-export function vars(raw) {
-  const list = Array.isArray(raw) ? raw : String(raw == null ? DEFAULT_VARS : raw).split(/[\n,]/);
-  return list.map((v) => String(v).trim().replace(/^\{\{\s*|\s*\}\}$/g, '')).filter(Boolean);
-}
-
-/** Which prop field a merge tag lands in when inserted from the Data tab, keyed by the selected block's type. */
-export const INSERT_KEYS = { text: 'html', heading: 'text', button: 'label', html: 'code', codeblock: 'code', quote: 'text', list: 'items', table: 'data' };
+export const DEFAULT_VARS = 'first_name\nlast_name\nemail\ncompany\ncity\norder_id\nplan\ndiscount\nunsubscribe_url';
+export const TOKEN = (t) => '{' + '{ ' + t + ' }' + '}';
+
+/** Variables are supplied by the host application -- the editor only ever shows the tokens, never a substituted value. */
+export function vars(raw) {
+  const list = Array.isArray(raw) ? raw : String(raw == null ? DEFAULT_VARS : raw).split(/[\n,]/);
+  return list.map((v) => String(v).trim().replace(/^\{\{\s*|\s*\}\}$/g, '')).filter(Boolean);
+}
+
+/** Which prop field a merge tag lands in when inserted from the Data tab, keyed by the selected block's type. */
+export const INSERT_KEYS = { text: 'html', heading: 'text', button: 'label', html: 'code', codeblock: 'code', quote: 'text', list: 'items', table: 'data' };

package/src/mailcraft-editor.js

@@ -96,8 +96,10 @@ function tip(node, label, dir, align) {
  * a host's own table, an imported locale from `core/i18n/`, or both merged via
  * `defineMessages`; see `core/i18n/index.js`).
  * Methods: `getContent()`, `setContent(doc)`, `importHtml(html)`, `exportHtml()`,
- * `loadTemplate(tpl)`, `screenshotPng()`
- * (full-template PNG as a Blob), `previewScreenshot()` (story-style viewer),
+ * `loadTemplate(tpl)`, `screenshotPng(options)`
+ * (full-template image as a Blob; `options.format`/`quality`/`scale` pick
+ * PNG, JPEG or WebP and the compression), `previewScreenshot()` (story-style
+ * viewer with its own format picker),
  * `downloadScreenshot()`, `copyScreenshot()`, `undo()`, `redo()`.
  * Events: `change` (detail: doc), `export` (detail: html string).
  */
@@ -473,20 +475,34 @@ export class MailCraftEditor extends ElementBase {
     return html;
   }
 
-  /** Full-template screenshot as a PNG Blob (2x resolution, desktop width, independent of the current device/zoom view). See render/screenshot.js for the technique and its limits. */
-  screenshotPng() { return captureTemplatePng(this.core, this.mc); }
+  /**
+   * Full-template screenshot as an image Blob (2x resolution by default,
+   * desktop width, independent of the current device/zoom view). `options`
+   * is the compression dial: `{ format: 'png' | 'jpeg' | 'webp', quality:
+   * 0..1 (lossy formats, default 0.85), scale (default 2) }`. PNG is
+   * lossless; JPEG/WebP are typically a fraction of the size on a long
+   * template. Read the returned `blob.type` for what was actually encoded --
+   * a browser without a WebP encoder hands back PNG. See
+   * render/screenshot.js for the technique and its limits.
+   */
+  screenshotPng(options) { return captureTemplatePng(this.core, this.mc, options); }
 
-  /** Opens the story-style viewer over the editor and captures into it -- what the Screenshot button does. Nothing touches the filesystem until the user picks Download inside it. */
-  previewScreenshot() { this.story.open(); }
+  /** Opens the story-style viewer over the editor and captures into it -- what the Screenshot button does. The export dialog, which hosts that button, is parked while the viewer is up and restored when it closes, so the two never read as stacked modals. Nothing touches the filesystem until the user picks Download inside it. */
+  previewScreenshot() {
+    const fromExport = this.core.state.exportOpen;
+    if (fromExport) this.core.setState({ exportOpen: false });
+    this.story.open(fromExport ? { onClose: () => this.core.setState({ exportOpen: true }) } : undefined);
+  }
 
-  /** `screenshotPng()` plus the same save-a-file flow as the HTML export download, with success/failure toasts. Pass an already-captured blob (the story viewer does) to save that one instead of rendering a second time. */
-  async downloadScreenshot(blob) {
+  /** `screenshotPng(options)` plus the same save-a-file flow as the HTML export download, with success/failure toasts. Pass an already-captured blob (the story viewer does) to save that one instead of rendering a second time; the filename extension follows the blob's actual type. */
+  async downloadScreenshot(blob, options) {
     const t = this.core.t;
     try {
-      const png = blob || await this.screenshotPng();
+      const png = blob || await this.screenshotPng(options);
+      const ext = { 'image/jpeg': 'jpg', 'image/webp': 'webp' }[png.type] || 'png';
       const a = document.createElement('a');
       a.href = URL.createObjectURL(png);
-      a.download = 'email.png';
+      a.download = 'email.' + ext;
       a.click();
       setTimeout(() => URL.revokeObjectURL(a.href), 1500);
       this.core.flash(t('toast.pngSaved'));

package/src/render/focus-preserve.js

@@ -1,158 +1,158 @@
-/**
- * The original relies on React's reconciliation to keep a focused `<input>`'s
- * DOM node alive across a per-keystroke re-render (Design-tab fields, the
- * campaign title, AI brief/goal/tone, search boxes, the code textarea all
- * commit on every `input` event, not just on blur). This renderer has no
- * VDOM -- it rebuilds DOM from scratch -- so without this, typing a single
- * character into any of those fields would lose focus immediately after.
- *
- * The fix: every such input (and every RTE-edited block: text, heading, box,
- * html) carries a stable `data-focus-key`. Before a rebuild, capture the
- * focused element's key + selection range; after, find the new element with
- * the same key and restore focus and the caret position, so the net effect
- * matches React's outcome even though the DOM node identity changed.
- *
- * Contenteditable blocks need this just as much as plain inputs: focusing
- * one sets `core.state.editing`, and `EditorCore.mountKeyboard`'s
- * `selectionchange` listener refreshes the toolbar's active states on every
- * caret move. Without
- * caret-position restoration here, that would blow away and recreate the
- * focused div each time, so the very first keystroke would silently drop
- * focus and the RTE toolbar would appear to do nothing.
- */
-export function withFocusPreserved(root, rebuild) {
-  const active = root.activeElement;
-  const key = active && active.dataset ? active.dataset.focusKey : null;
-  let selStart = null; let selEnd = null; let scrollTop = null; let editable = false;
-  // A range slider mid-drag is the one focus-preservation case where
-  // restoring focus on a rebuilt node isn't enough: dragging its thumb is a
-  // native, implicit mouse capture tied to that exact element, and replacing
-  // the element (as every other rebuilt input does here) silently drops that
-  // capture -- the thumb stops tracking the mouse and the slider feels like
-  // it's snapping/jumping instead of gliding. So this one case skips
-  // rebuilding the node entirely: the live element is pulled out before
-  // `rebuild()` and spliced back into the freshly-built tree afterward.
-  const rangeNode = key && active.tagName === 'INPUT' && active.type === 'range' ? active : null;
-  if (rangeNode) {
-    // nothing to capture -- the node itself is preserved below, after rebuild()
-  } else if (key && (active.tagName === 'INPUT' || active.tagName === 'TEXTAREA')) {
-    try { selStart = active.selectionStart; selEnd = active.selectionEnd; } catch { /* some input types don't support selection */ }
-    scrollTop = active.scrollTop;
-  } else if (key && active.isContentEditable) {
-    editable = true;
-    const sel = shadowSelection(root);
-    if (sel && sel.rangeCount && active.contains(sel.anchorNode)) {
-      const range = sel.getRangeAt(0);
-      selStart = textOffset(active, range.startContainer, range.startOffset);
-      selEnd = textOffset(active, range.endContainer, range.endOffset);
-    }
-    scrollTop = active.scrollTop;
-  }
-
-  rebuild();
-
-  if (!key) return;
-  const next = root.querySelector(`[data-focus-key="${cssEscape(key)}"]`);
-  if (!next) return;
-  if (rangeNode) {
-    for (const attr of ['min', 'max', 'step']) {
-      const v = next.getAttribute(attr);
-      if (v === null) rangeNode.removeAttribute(attr); else rangeNode.setAttribute(attr, v);
-    }
-    next.replaceWith(rangeNode);
-    return;
-  }
-  if (editable) {
-    // Set the Range *before* focusing: focusing a contenteditable establishes
-    // its own default collapsed selection as a side effect, and doing that
-    // after we've placed the real caret fires a second, out-of-order
-    // `selectionchange` notification for that now-stale default -- which
-    // arrives *after* the one for our real restore, so it looks like a fresh,
-    // later selection change and clobbers the correct caret right back to
-    // collapsed. Setting the range first means `.focus()` adopts the
-    // selection that's already there instead of replacing it.
-    if (selStart != null) {
-      try {
-        const range = document.createRange();
-        setPointAtOffset(range, next, selStart, true);
-        setPointAtOffset(range, next, selEnd, false);
-        const sel = shadowSelection(root);
-        sel.removeAllRanges();
-        sel.addRange(range);
-      } catch { /* ignore -- element structure changed under the caret */ }
-    }
-    // `preventScroll` matters a lot here: this `.focus()` fires on every
-    // re-render of a block mid-edit (every keystroke), not just once. Without
-    // it, the browser's default focus-scroll-into-view runs every time --
-    // harmless on a short template, but on a long one it yanks the canvas
-    // back toward the focused block on every keystroke, fighting whatever
-    // scroll position the user actually had.
-    next.focus({ preventScroll: true });
-  } else {
-    next.focus({ preventScroll: true });
-    if (selStart != null) {
-      try { next.setSelectionRange(selStart, selEnd); } catch { /* ignore */ }
-    }
-  }
-  if (scrollTop != null) next.scrollTop = scrollTop;
-}
-
-/**
- * `document.getSelection()`/`window.getSelection()` is redacted to the host
- * document when the real selection lives inside an open shadow root -- in
- * Chrome its `anchorNode` reports as `<body>` rather than the actual text
- * node being edited, even though the visible caret and `execCommand` both
- * still operate on the real position. Reading through that redacted object
- * (as this file needs to, to compute/restore a caret offset) silently gives
- * back garbage -- not an error, just always "position 0" -- which is what
- * made every re-render-while-typing reset the caret to the start and type
- * new characters in reverse. `ShadowRoot.getSelection()` (Chromium-only; no
- * standard equivalent yet) reports the real node/offset.
- */
-function shadowSelection(root) {
-  return typeof root.getSelection === 'function' ? root.getSelection() : window.getSelection();
-}
-
-/** Character offset of (node, offset) counting only text within `root`, walking in document order. */
-export function textOffset(root, node, offset) {
-  if (node.nodeType !== Node.TEXT_NODE) {
-    // A range boundary can land on an element (e.g. offset counts child nodes) --
-    // resolve it to the text position right before its `offset`-th child.
-    let n = 0;
-    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
-    let cur; let target = node.childNodes[offset];
-    if (!target) { while (walker.nextNode()) n += walker.currentNode.nodeValue.length; return n; }
-    while ((cur = walker.nextNode())) { if (cur === target || target.contains(cur)) return n; n += cur.nodeValue.length; }
-    return n;
-  }
-  let n = 0;
-  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
-  let cur;
-  while ((cur = walker.nextNode())) {
-    if (cur === node) return n + offset;
-    n += cur.nodeValue.length;
-  }
-  return n;
-}
-
-/** Sets the start or end point of `range` to the text-offset position inside `root`. */
-function setPointAtOffset(range, root, targetOffset, isStart) {
-  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
-  let n = 0; let cur; let last = null;
-  while ((cur = walker.nextNode())) {
-    last = cur;
-    const len = cur.nodeValue.length;
-    if (n + len >= targetOffset) {
-      const point = targetOffset - n;
-      if (isStart) range.setStart(cur, point); else range.setEnd(cur, point);
-      return;
-    }
-    n += len;
-  }
-  if (last) { if (isStart) range.setStart(last, last.nodeValue.length); else range.setEnd(last, last.nodeValue.length); }
-  else { if (isStart) range.setStart(root, 0); else range.setEnd(root, 0); }
-}
-
-function cssEscape(s) {
-  return String(s).replace(/["\\]/g, '\\$&');
-}
+/**
+ * The original relies on React's reconciliation to keep a focused `<input>`'s
+ * DOM node alive across a per-keystroke re-render (Design-tab fields, the
+ * campaign title, AI brief/goal/tone, search boxes, the code textarea all
+ * commit on every `input` event, not just on blur). This renderer has no
+ * VDOM -- it rebuilds DOM from scratch -- so without this, typing a single
+ * character into any of those fields would lose focus immediately after.
+ *
+ * The fix: every such input (and every RTE-edited block: text, heading, box,
+ * html) carries a stable `data-focus-key`. Before a rebuild, capture the
+ * focused element's key + selection range; after, find the new element with
+ * the same key and restore focus and the caret position, so the net effect
+ * matches React's outcome even though the DOM node identity changed.
+ *
+ * Contenteditable blocks need this just as much as plain inputs: focusing
+ * one sets `core.state.editing`, and `EditorCore.mountKeyboard`'s
+ * `selectionchange` listener refreshes the toolbar's active states on every
+ * caret move. Without
+ * caret-position restoration here, that would blow away and recreate the
+ * focused div each time, so the very first keystroke would silently drop
+ * focus and the RTE toolbar would appear to do nothing.
+ */
+export function withFocusPreserved(root, rebuild) {
+  const active = root.activeElement;
+  const key = active && active.dataset ? active.dataset.focusKey : null;
+  let selStart = null; let selEnd = null; let scrollTop = null; let editable = false;
+  // A range slider mid-drag is the one focus-preservation case where
+  // restoring focus on a rebuilt node isn't enough: dragging its thumb is a
+  // native, implicit mouse capture tied to that exact element, and replacing
+  // the element (as every other rebuilt input does here) silently drops that
+  // capture -- the thumb stops tracking the mouse and the slider feels like
+  // it's snapping/jumping instead of gliding. So this one case skips
+  // rebuilding the node entirely: the live element is pulled out before
+  // `rebuild()` and spliced back into the freshly-built tree afterward.
+  const rangeNode = key && active.tagName === 'INPUT' && active.type === 'range' ? active : null;
+  if (rangeNode) {
+    // nothing to capture -- the node itself is preserved below, after rebuild()
+  } else if (key && (active.tagName === 'INPUT' || active.tagName === 'TEXTAREA')) {
+    try { selStart = active.selectionStart; selEnd = active.selectionEnd; } catch { /* some input types don't support selection */ }
+    scrollTop = active.scrollTop;
+  } else if (key && active.isContentEditable) {
+    editable = true;
+    const sel = shadowSelection(root);
+    if (sel && sel.rangeCount && active.contains(sel.anchorNode)) {
+      const range = sel.getRangeAt(0);
+      selStart = textOffset(active, range.startContainer, range.startOffset);
+      selEnd = textOffset(active, range.endContainer, range.endOffset);
+    }
+    scrollTop = active.scrollTop;
+  }
+
+  rebuild();
+
+  if (!key) return;
+  const next = root.querySelector(`[data-focus-key="${cssEscape(key)}"]`);
+  if (!next) return;
+  if (rangeNode) {
+    for (const attr of ['min', 'max', 'step']) {
+      const v = next.getAttribute(attr);
+      if (v === null) rangeNode.removeAttribute(attr); else rangeNode.setAttribute(attr, v);
+    }
+    next.replaceWith(rangeNode);
+    return;
+  }
+  if (editable) {
+    // Set the Range *before* focusing: focusing a contenteditable establishes
+    // its own default collapsed selection as a side effect, and doing that
+    // after we've placed the real caret fires a second, out-of-order
+    // `selectionchange` notification for that now-stale default -- which
+    // arrives *after* the one for our real restore, so it looks like a fresh,
+    // later selection change and clobbers the correct caret right back to
+    // collapsed. Setting the range first means `.focus()` adopts the
+    // selection that's already there instead of replacing it.
+    if (selStart != null) {
+      try {
+        const range = document.createRange();
+        setPointAtOffset(range, next, selStart, true);
+        setPointAtOffset(range, next, selEnd, false);
+        const sel = shadowSelection(root);
+        sel.removeAllRanges();
+        sel.addRange(range);
+      } catch { /* ignore -- element structure changed under the caret */ }
+    }
+    // `preventScroll` matters a lot here: this `.focus()` fires on every
+    // re-render of a block mid-edit (every keystroke), not just once. Without
+    // it, the browser's default focus-scroll-into-view runs every time --
+    // harmless on a short template, but on a long one it yanks the canvas
+    // back toward the focused block on every keystroke, fighting whatever
+    // scroll position the user actually had.
+    next.focus({ preventScroll: true });
+  } else {
+    next.focus({ preventScroll: true });
+    if (selStart != null) {
+      try { next.setSelectionRange(selStart, selEnd); } catch { /* ignore */ }
+    }
+  }
+  if (scrollTop != null) next.scrollTop = scrollTop;
+}
+
+/**
+ * `document.getSelection()`/`window.getSelection()` is redacted to the host
+ * document when the real selection lives inside an open shadow root -- in
+ * Chrome its `anchorNode` reports as `<body>` rather than the actual text
+ * node being edited, even though the visible caret and `execCommand` both
+ * still operate on the real position. Reading through that redacted object
+ * (as this file needs to, to compute/restore a caret offset) silently gives
+ * back garbage -- not an error, just always "position 0" -- which is what
+ * made every re-render-while-typing reset the caret to the start and type
+ * new characters in reverse. `ShadowRoot.getSelection()` (Chromium-only; no
+ * standard equivalent yet) reports the real node/offset.
+ */
+function shadowSelection(root) {
+  return typeof root.getSelection === 'function' ? root.getSelection() : window.getSelection();
+}
+
+/** Character offset of (node, offset) counting only text within `root`, walking in document order. */
+export function textOffset(root, node, offset) {
+  if (node.nodeType !== Node.TEXT_NODE) {
+    // A range boundary can land on an element (e.g. offset counts child nodes) --
+    // resolve it to the text position right before its `offset`-th child.
+    let n = 0;
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+    let cur; let target = node.childNodes[offset];
+    if (!target) { while (walker.nextNode()) n += walker.currentNode.nodeValue.length; return n; }
+    while ((cur = walker.nextNode())) { if (cur === target || target.contains(cur)) return n; n += cur.nodeValue.length; }
+    return n;
+  }
+  let n = 0;
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+  let cur;
+  while ((cur = walker.nextNode())) {
+    if (cur === node) return n + offset;
+    n += cur.nodeValue.length;
+  }
+  return n;
+}
+
+/** Sets the start or end point of `range` to the text-offset position inside `root`. */
+function setPointAtOffset(range, root, targetOffset, isStart) {
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+  let n = 0; let cur; let last = null;
+  while ((cur = walker.nextNode())) {
+    last = cur;
+    const len = cur.nodeValue.length;
+    if (n + len >= targetOffset) {
+      const point = targetOffset - n;
+      if (isStart) range.setStart(cur, point); else range.setEnd(cur, point);
+      return;
+    }
+    n += len;
+  }
+  if (last) { if (isStart) range.setStart(last, last.nodeValue.length); else range.setEnd(last, last.nodeValue.length); }
+  else { if (isStart) range.setStart(root, 0); else range.setEnd(root, 0); }
+}
+
+function cssEscape(s) {
+  return String(s).replace(/["\\]/g, '\\$&');
+}

package/src/render/screenshot.js

@@ -31,8 +31,46 @@ import { renderDoc } from './canvas.js';
 
 const BLANK_PIXEL = 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7';
 
+/** Encodings the capture can produce. Anything unrecognized falls back to PNG. */
+const MIME = { png: 'image/png', jpeg: 'image/jpeg', jpg: 'image/jpeg', webp: 'image/webp' };
+
+/**
+ * `{ scale, format, quality }` with every hole filled. A bare number is the
+ * legacy third argument (scale). `quality` only matters to the lossy formats;
+ * canvas encoders take 0..1, and out-of-range input falls back to the default
+ * rather than clamping to an extreme the caller clearly did not mean.
+ */
+function shotOptions(options) {
+  const o = typeof options === 'number' ? { scale: options } : options || {};
+  const q = Number(o.quality);
+  return {
+    scale: Number(o.scale) > 0 ? Number(o.scale) : 2,
+    mime: MIME[String(o.format || 'png').toLowerCase()] || 'image/png',
+    quality: q >= 0 && q <= 1 ? q : 0.85,
+  };
+}
+
+/**
+ * `canvas.toBlob` wrapped as a promise. A browser that cannot encode the
+ * requested type is allowed by spec to hand back PNG instead (Safari does
+ * this for WebP), so callers read `blob.type` rather than trusting the
+ * request.
+ */
+function encodeCanvas(canvas, mime, quality) {
+  return new Promise((resolve, reject) => {
+    canvas.toBlob((b) => (b ? resolve(b) : reject(new Error('image encoding failed'))), mime, quality);
+  });
+}
+
+// Inlined bytes are cached per URL for the session: every capture (open,
+// retry, reopen) used to re-fetch each remote image, which is most of a slow
+// open on a photo-heavy template. A failed fetch is evicted so a transient
+// network error does not pin the blank-pixel fallback forever.
+const inlineCache = new Map();
+
 function toDataUri(url) {
-  return fetch(url, { mode: 'cors' }).then((res) => {
+  if (inlineCache.has(url)) return inlineCache.get(url);
+  const job = fetch(url, { mode: 'cors' }).then((res) => {
     if (!res.ok) throw new Error('fetch failed: ' + res.status);
     return res.blob();
   }).then((blob) => new Promise((resolve, reject) => {
@@ -40,7 +78,12 @@ function toDataUri(url) {
     fr.onload = () => resolve(fr.result);
     fr.onerror = reject;
     fr.readAsDataURL(blob);
-  }));
+  })).catch((err) => {
+    inlineCache.delete(url);
+    throw err;
+  });
+  inlineCache.set(url, job);
+  return job;
 }
 
 async function inlineExternalImages(root) {
@@ -66,7 +109,13 @@ async function inlineExternalImages(root) {
 
 /**
  * Renders the current document full-length (desktop width, independent of
- * the device toggle and zoom) and returns a PNG Blob at `scale`x resolution.
+ * the device toggle and zoom) and returns an image Blob. `options` is either
+ * a bare scale number (the legacy signature) or
+ * `{ scale = 2, format = 'png' | 'jpeg' | 'webp', quality = 0.85 }` --
+ * `format`/`quality` are the compression dial: PNG is lossless and biggest,
+ * JPEG and WebP are lossy and typically a fraction of the size on a long
+ * template. Check the returned `blob.type` for what was actually encoded
+ * (a browser without a WebP encoder hands back PNG).
  * `mountInto` is any attached container inside the editor's shadow root --
  * the tree must live in the live document briefly, off-screen, to lay out
  * and be measured before serialization.
@@ -74,7 +123,8 @@ async function inlineExternalImages(root) {
  * (`export const` + async function expression, not `export async function`:
  * build.js's transform only recognizes `export (const|function|class)`.)
  */
-export const captureTemplatePng = async function (core, mountInto, scale = 2) {
+export const captureTemplatePng = async function (core, mountInto, options) {
+  const { scale, mime, quality } = shotOptions(options);
   const theme = core.state.doc.theme;
   const pad = 32;
   const wrapper = document.createElement('div');
@@ -139,11 +189,49 @@ export const captureTemplatePng = async function (core, mountInto, scale = 2) {
     canvas.width = Math.max(1, Math.round(w * fit));
     canvas.height = Math.max(1, Math.round(h * fit));
     const ctx = canvas.getContext('2d');
+    // The lossy formats carry no alpha channel, and an unpainted canvas pixel
+    // encodes as black in JPEG -- lay the page colour down first.
+    if (mime !== 'image/png') {
+      ctx.fillStyle = theme.bg || '#ffffff';
+      ctx.fillRect(0, 0, canvas.width, canvas.height);
+    }
     ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
-    return await new Promise((resolve, reject) => {
-      canvas.toBlob((b) => (b ? resolve(b) : reject(new Error('PNG encoding failed'))), 'image/png');
-    });
+    return await encodeCanvas(canvas, mime, quality);
   } finally {
     wrapper.remove();
   }
 };
+
+/**
+ * Re-encodes an already-captured shot without rendering the template again:
+ * the story viewer captures once as PNG (lossless for the preview and the
+ * clipboard, which only accepts `image/png`) and converts here only when the
+ * user downloads as JPG or WebP. `bg` fills behind the pixels for the lossy
+ * formats. Same caveat as the capture: read the returned `blob.type`.
+ */
+export const transcodeShot = async function (blob, options, bg) {
+  const { mime, quality } = shotOptions(options);
+  if (mime === 'image/png' && blob.type === 'image/png') return blob;
+  const url = URL.createObjectURL(blob);
+  try {
+    const img = new Image();
+    await new Promise((resolve, reject) => {
+      img.onload = resolve;
+      img.onerror = () => reject(new Error('shot decode failed'));
+      img.src = url;
+    });
+    if (img.decode) await img.decode().catch(() => {});
+    const canvas = document.createElement('canvas');
+    canvas.width = Math.max(1, img.naturalWidth);
+    canvas.height = Math.max(1, img.naturalHeight);
+    const ctx = canvas.getContext('2d');
+    if (mime !== 'image/png') {
+      ctx.fillStyle = bg || '#ffffff';
+      ctx.fillRect(0, 0, canvas.width, canvas.height);
+    }
+    ctx.drawImage(img, 0, 0);
+    return await encodeCanvas(canvas, mime, quality);
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+};