@fraziym/axoniz 0.1.0

package/dist/web/static/js/editor/canvas-coords.js

@@ -0,0 +1,21 @@
+/**
+ * Convert a pointer event's client coordinates into the canvas's
+ * internal pixel coordinates, accounting for current display scale.
+ *
+ * Handles both mouse and the first finger of a touch event.
+ *
+ * @param {MouseEvent|TouchEvent} e
+ * @param {HTMLCanvasElement} canvas
+ * @returns {{x: number, y: number}}
+ */
+export function canvasCoords(e, canvas) {
+  const rect = canvas.getBoundingClientRect();
+  const scaleX = canvas.width / rect.width;
+  const scaleY = canvas.height / rect.height;
+  const clientX = e.touches ? e.touches[0].clientX : e.clientX;
+  const clientY = e.touches ? e.touches[0].clientY : e.clientY;
+  return {
+    x: (clientX - rect.left) * scaleX,
+    y: (clientY - rect.top) * scaleY,
+  };
+}

package/dist/web/static/js/editor/canvas-events.js

@@ -0,0 +1,197 @@
+/**
+ * Canvas event wiring — mouse, touch (including pinch-zoom on two
+ * fingers), and the canvas-area pan handler.
+ *
+ *   Mouse:
+ *     mousedown on canvas    → beginDraw
+ *     mousemove on window    → continueDraw (window so a drag can
+ *                              continue past the canvas edge)
+ *     mouseup on window      → endDraw
+ *     mouseenter/mouseleave  → show/hide the brush-cursor overlay
+ *     mousedown on canvas-area (NOT on the canvas itself, lasso only)
+ *                            → beginDraw (lasso starts outside canvas)
+ *
+ *   Touch:
+ *     touchstart 1 finger    → beginDraw
+ *     touchmove  1 finger    → continueDraw
+ *     touchend / touchcancel → endDraw
+ *     touchstart 2 fingers   → pinch-zoom + 2-finger pan
+ *
+ *   Pan (any free space around the canvas):
+ *     pointerdown / pointermove / pointerup on canvas-area, skipping
+ *     the canvas + transform overlay + UI elements above them. Sets
+ *     canvasArea.dataset.panX/Y + CSS transform on both canvases.
+ *
+ *   Exposes `canvasArea._resetPan()` so the zoom/fit reset can clear
+ *   the pan offset.
+ *
+ * @param {{
+ *   canvasArea:        HTMLDivElement,
+ *   beginDraw:         (e: Event) => void,
+ *   continueDraw:      (e: Event) => void,
+ *   endDraw:           (e?: Event) => void,
+ *   updateBrushCursor: (e: Event) => void,
+ *   syncZoomControls?: () => void,
+ * }} ctx
+ */
+import { state } from './state.js';
+
+export function wireCanvasEvents({ canvasArea, beginDraw, continueDraw, endDraw, updateBrushCursor, syncZoomControls }) {
+  // Mouse — mousedown stays on the canvas; mousemove/up are bound to
+  // the WINDOW so a drag can continue (and end) past the canvas edge.
+  // Critical for the Resize tool where users overshoot.
+  state.mainCanvas.addEventListener('mousedown', beginDraw);
+  window.addEventListener('mousemove', continueDraw);
+  window.addEventListener('mouseup', endDraw);
+  // Lasso can start OUTSIDE the canvas — fallback mousedown on the
+  // surrounding canvas-area so the user can begin a lasso path in
+  // the empty space around the image. Other tools stay canvas-only.
+  canvasArea.addEventListener('mousedown', (e) => {
+    if (state.tool !== 'lasso') return;
+    if (e.target === state.mainCanvas) return; // already handled
+    beginDraw(e);
+  });
+  state.mainCanvas.addEventListener('mouseenter', (e) => {
+    if (['brush', 'eraser', 'inpaint', 'lasso', 'clone'].includes(state.tool)) updateBrushCursor(e);
+  });
+  state.mainCanvas.addEventListener('mouseleave', () => {
+    // Only hide the brush-cursor overlay on leave — DO NOT end the
+    // drag, so the user can drag a resize handle past the canvas edge.
+    if (state.cursorEl) state.cursorEl.style.display = 'none';
+  });
+
+  // Touch — single finger draws; two fingers pan + pinch-zoom.
+  let multiActive = false;
+  let multiStartDist = 0;
+  let multiStartZoom = 1;
+  let multiStartCenter = { x: 0, y: 0 };
+  let multiStartPan = { x: 0, y: 0 };
+  const touchInfo = (e) => {
+    const t1 = e.touches[0], t2 = e.touches[1];
+    const cx = (t1.clientX + t2.clientX) / 2;
+    const cy = (t1.clientY + t2.clientY) / 2;
+    const dx = t2.clientX - t1.clientX;
+    const dy = t2.clientY - t1.clientY;
+    return { cx, cy, dist: Math.hypot(dx, dy) };
+  };
+  const applyCanvasOffset = (x, y) => {
+    canvasArea.dataset.panX = String(x);
+    canvasArea.dataset.panY = String(y);
+    const t = `translate3d(${x}px, ${y}px, 0)`;
+    state.mainCanvas.style.transform = t;
+    if (state.transformOverlay) state.transformOverlay.style.transform = t;
+  };
+  state.mainCanvas.addEventListener('touchstart', (e) => {
+    e.preventDefault();
+    if (e.touches.length >= 2) {
+      // End any in-progress single-finger draw before switching modes.
+      if (!multiActive) endDraw();
+      multiActive = true;
+      const info = touchInfo(e);
+      multiStartDist = info.dist;
+      multiStartZoom = state.zoom;
+      multiStartCenter = { x: info.cx, y: info.cy };
+      multiStartPan = {
+        x: parseFloat(canvasArea.dataset.panX || '0') || 0,
+        y: parseFloat(canvasArea.dataset.panY || '0') || 0,
+      };
+      return;
+    }
+    if (multiActive) return;
+    beginDraw(e);
+  }, { passive: false });
+  state.mainCanvas.addEventListener('touchmove', (e) => {
+    e.preventDefault();
+    if (multiActive && e.touches.length >= 2) {
+      const info = touchInfo(e);
+      const ratio = info.dist / Math.max(1, multiStartDist);
+      const newZoom = Math.max(0.1, Math.min(5, multiStartZoom * ratio));
+      if (Math.abs(newZoom - state.zoom) > 0.001) {
+        state.zoom = newZoom;
+        state.mainCanvas.style.width = (state.imgWidth * state.zoom) + 'px';
+        state.mainCanvas.style.height = (state.imgHeight * state.zoom) + 'px';
+        const label = state.container.querySelector('.ge-zoom-label');
+        if (label) label.textContent = Math.round(state.zoom * 100) + '%';
+        syncZoomControls?.();
+      }
+      const dx = info.cx - multiStartCenter.x;
+      const dy = info.cy - multiStartCenter.y;
+      applyCanvasOffset(multiStartPan.x + dx, multiStartPan.y + dy);
+      return;
+    }
+    if (multiActive) return;
+    continueDraw(e);
+  }, { passive: false });
+  state.mainCanvas.addEventListener('touchend', (e) => {
+    if (multiActive) {
+      if (e.touches.length < 2) multiActive = false;
+      return;
+    }
+    endDraw(e);
+  });
+  state.mainCanvas.addEventListener('touchcancel', () => {
+    multiActive = false;
+    endDraw();
+  });
+
+  // Press-and-drag in the empty space AROUND the canvas pans the
+  // canvas + overlay via CSS transform. Works even when the image
+  // fits the viewport (no scroll needed). Skips presses on the canvas
+  // itself (the canvas owns its own drawing input) or on UI elements
+  // above it.
+  let panning = false;
+  let pid = null;
+  let startX = 0, startY = 0;
+  const getOffset = () => {
+    const v = canvasArea.dataset.panX || '0';
+    const u = canvasArea.dataset.panY || '0';
+    return { x: parseFloat(v) || 0, y: parseFloat(u) || 0 };
+  };
+  const applyOffset = (x, y) => {
+    canvasArea.dataset.panX = String(x);
+    canvasArea.dataset.panY = String(y);
+    const t = `translate3d(${x}px, ${y}px, 0)`;
+    state.mainCanvas.style.transform = t;
+    if (state.transformOverlay) state.transformOverlay.style.transform = t;
+  };
+  canvasArea.addEventListener('pointerdown', (e) => {
+    if (state.tool === 'lasso') return;
+    if (e.target === state.mainCanvas || e.target === state.transformOverlay) return;
+    if (e.target.closest('button, input, .ge-adj-popup, .ge-transform-popup, .ge-fx-popup, .ge-inpaint-popup, .ge-controls, .ge-right-panel, .ge-fx-menu')) return;
+    // During an active transform the corner/rotation handles render
+    // OUTSIDE the canvas (over the surrounding area), and the overlay is
+    // pointer-events:none — so a grab on an outside handle lands here.
+    // Route it to the transform tool (getHandleAt works in image space,
+    // even for points beyond the canvas) instead of panning the canvas.
+    if (state.transformActive) {
+      beginDraw(e);
+      // Only swallow the event (skip pan) if a handle was grabbed OR the
+      // layer-move fallback engaged; otherwise let the pan logic below
+      // run so empty space still pans while the transform tool is open.
+      if (state.transformHandle || state.moving) return;
+    }
+    const off = getOffset();
+    panning = true;
+    pid = e.pointerId;
+    startX = e.clientX - off.x;
+    startY = e.clientY - off.y;
+    try { canvasArea.setPointerCapture(pid); } catch {}
+    canvasArea.style.cursor = 'grabbing';
+    e.preventDefault();
+  });
+  canvasArea.addEventListener('pointermove', (e) => {
+    if (!panning || e.pointerId !== pid) return;
+    applyOffset(e.clientX - startX, e.clientY - startY);
+  });
+  const endPan = () => {
+    if (!panning) return;
+    panning = false;
+    try { canvasArea.releasePointerCapture(pid); } catch {}
+    pid = null;
+    canvasArea.style.cursor = '';
+  };
+  canvasArea.addEventListener('pointerup', endPan);
+  canvasArea.addEventListener('pointercancel', endPan);
+  // Reset offset whenever zoom/fit changes the canvas size.
+  canvasArea._resetPan = () => applyOffset(0, 0);
+}

package/dist/web/static/js/editor/canvas-transforms.js

@@ -0,0 +1,132 @@
+/**
+ * Whole-document transforms: rotate by 90/180/270° or flip horizontal/
+ * vertical. These mutate every layer's canvas + the offset map + the
+ * document's overall width/height so the result feels like the whole
+ * image rotated as one piece.
+ *
+ * Pure-ish — reads/writes shared state directly; the factory takes a
+ * small dep bag for the orchestration plumbing (undo snapshot, canvas
+ * loading overlay, fit-zoom-to-viewport, composite redraw).
+ *
+ * @param {{
+ *   saveState:           (label?: string) => void,
+ *   composite:           () => void,
+ *   fitZoom:             () => void,
+ *   showCanvasLoading:   (label: string) => void,
+ *   hideCanvasLoading:   () => void,
+ * }} deps
+ */
+import { state } from './state.js';
+
+export function createCanvasTransforms({ saveState, composite, fitZoom, showCanvasLoading, hideCanvasLoading }) {
+  return {
+    /**
+     * Rotate the entire document by `deg` (90 / 180 / 270). 90 and 270
+     * swap canvas dimensions. Each layer is rotated around its own
+     * centre, then its centre is rotated around the old image centre
+     * and translated into the new image's frame.
+     *
+     * Wrapped in requestAnimationFrame because the rotation pass can
+     * block the UI for 0.5–2 s on big images — the spinner overlay
+     * paints before we block.
+     */
+    rotateAll(deg) {
+      if (!state.layers.length) return;
+      saveState(`Rotate ${deg}°`);
+      showCanvasLoading('Rotating…');
+      const oldW = state.imgWidth, oldH = state.imgHeight;
+      const swap = (deg === 90 || deg === 270);
+      const newW = swap ? oldH : oldW;
+      const newH = swap ? oldW : oldH;
+      const rad = (deg * Math.PI) / 180;
+      const cos = Math.cos(rad), sin = Math.sin(rad);
+      requestAnimationFrame(() => {
+        try {
+          for (const layer of state.layers) {
+            const lw = layer.canvas.width, lh = layer.canvas.height;
+            const off = state.layerOffsets.get(layer.id) || { x: 0, y: 0 };
+            // Layer centre in old image coords.
+            const cx = off.x + lw / 2;
+            const cy = off.y + lh / 2;
+            // Rotate the centre around the old image centre and
+            // translate so the new image centre lands at (newW/2, newH/2).
+            const dx = cx - oldW / 2;
+            const dy = cy - oldH / 2;
+            const nx = dx * cos - dy * sin + newW / 2;
+            const ny = dx * sin + dy * cos + newH / 2;
+            // New per-layer dims: swap when 90/270.
+            const newLw = swap ? lh : lw;
+            const newLh = swap ? lw : lh;
+            const tmp = document.createElement('canvas');
+            tmp.width = newLw; tmp.height = newLh;
+            const tctx = tmp.getContext('2d');
+            tctx.translate(newLw / 2, newLh / 2);
+            tctx.rotate(rad);
+            tctx.drawImage(layer.canvas, -lw / 2, -lh / 2);
+            layer.canvas.width = newLw;
+            layer.canvas.height = newLh;
+            layer.ctx.drawImage(tmp, 0, 0);
+            // The adjustment-render caches are keyed only by the adjustment
+            // signature, which rotation doesn't change — so composite would draw
+            // the STALE pre-rotation cache (the "had to click twice" bug). Drop
+            // them so the next composite re-renders from the rotated canvas.
+            layer._adjCacheKey = null;
+            layer._adjFinalKey = null;
+            state.layerOffsets.set(layer.id, {
+              x: Math.round(nx - newLw / 2),
+              y: Math.round(ny - newLh / 2),
+            });
+          }
+          state.imgWidth = newW;
+          state.imgHeight = newH;
+          state.mainCanvas.width = newW;
+          state.mainCanvas.height = newH;
+          if (state.maskCanvas) {
+            state.maskCanvas.width = newW;
+            state.maskCanvas.height = newH;
+          }
+          const sizeLabel = document.getElementById('ge-canvas-size');
+          if (sizeLabel) sizeLabel.textContent = `${newW}×${newH}`;
+          fitZoom();
+          composite();
+        } finally {
+          hideCanvasLoading();
+        }
+      });
+    },
+
+    /**
+     * Mirror every layer horizontally ('h') or vertically ('v').
+     * Canvas dimensions don't change. Each layer offset is reflected
+     * around the image centre.
+     */
+    flipAll(axis) {
+      if (!state.layers.length) return;
+      saveState(axis === 'h' ? 'Flip horizontal' : 'Flip vertical');
+      for (const layer of state.layers) {
+        const lw = layer.canvas.width, lh = layer.canvas.height;
+        const tmp = document.createElement('canvas');
+        tmp.width = lw; tmp.height = lh;
+        const tctx = tmp.getContext('2d');
+        tctx.save();
+        if (axis === 'h') { tctx.translate(lw, 0); tctx.scale(-1, 1); }
+        else              { tctx.translate(0, lh); tctx.scale(1, -1); }
+        tctx.drawImage(layer.canvas, 0, 0);
+        tctx.restore();
+        layer.ctx.clearRect(0, 0, lw, lh);
+        layer.ctx.drawImage(tmp, 0, 0);
+        // Invalidate the adjustment-render caches (keyed by adjustment sig only)
+        // so composite redraws from the flipped canvas, not a stale cache.
+        layer._adjCacheKey = null;
+        layer._adjFinalKey = null;
+        const off = state.layerOffsets.get(layer.id) || { x: 0, y: 0 };
+        if (axis === 'h') {
+          state.layerOffsets.set(layer.id, { x: state.imgWidth - off.x - lw, y: off.y });
+        } else {
+          state.layerOffsets.set(layer.id, { x: off.x, y: state.imgHeight - off.y - lh });
+        }
+      }
+      composite();
+    },
+  };
+}

package/dist/web/static/js/editor/checkerboard.js

@@ -0,0 +1,24 @@
+/**
+ * Paint a transparency-checkerboard pattern across the given canvas
+ * context. The editor uses this beneath every layer pass so empty
+ * (transparent) areas of the document are visible.
+ *
+ * Pure function — depends only on its arguments.
+ *
+ * @param {CanvasRenderingContext2D} ctx
+ * @param {number} w  Width in canvas pixels.
+ * @param {number} h  Height in canvas pixels.
+ */
+export function drawCheckerboard(ctx, w, h) {
+  const size = 10;
+  ctx.fillStyle = '#ccc';
+  ctx.fillRect(0, 0, w, h);
+  ctx.fillStyle = '#fff';
+  for (let y = 0; y < h; y += size) {
+    for (let x = 0; x < w; x += size) {
+      if ((Math.floor(x / size) + Math.floor(y / size)) % 2 === 0) {
+        ctx.fillRect(x, y, size, size);
+      }
+    }
+  }
+}

package/dist/web/static/js/editor/clipboard-and-drop.js

@@ -0,0 +1,133 @@
+/**
+ * Paste + drag-and-drop import handlers. Both add an image to the
+ * editor as a new layer:
+ *
+ *   - Paste (Ctrl+V): checks `state.internalClipboard` first (set by
+ *     lasso copy/cut), then falls back to the system clipboard's
+ *     `image/*` items. Layer is named "Pasted Selection" or "Pasted"
+ *     and becomes active; the tool snaps to Move so the user can
+ *     reposition it immediately.
+ *   - Drop: any `image/*` file dragged from the OS / another tab.
+ *     Shows a "Drop image to add as new layer" overlay mid-drag. Each
+ *     dropped image is routed through `handleImportedImage` so canvas-
+ *     resize prompts + undo history work the same as the toolbar
+ *     Import button.
+ *
+ * Both gated by `state.editorOpen` so they're inert when the editor
+ * is closed (other listeners on the page get first dibs).
+ *
+ * @param {{
+ *   container:            HTMLElement,
+ *   saveState:            (label?: string) => void,
+ *   createLayer:          (name: string, w: number, h: number) => object,
+ *   renderLayerPanel:     () => void,
+ *   composite:            () => void,
+ *   handleImportedImage:  (img: HTMLImageElement) => void,
+ *   uiModule:             object,
+ * }} deps
+ */
+import { state } from './state.js';
+
+export function wireClipboardAndDrop({
+  container, saveState, createLayer, renderLayerPanel, composite,
+  handleImportedImage, uiModule,
+}) {
+  // ── Paste ──
+  window.addEventListener('paste', (e) => {
+    if (!state.editorOpen) return;
+
+    function pasteAsLayer(imgSource, label) {
+      if (!state.editorOpen) return; // user closed mid-paste
+      saveState();
+      const layer = createLayer(label || 'Pasted', imgSource.width, imgSource.height);
+      layer.ctx.drawImage(imgSource, 0, 0);
+      state.layers.push(layer);
+      state.activeLayerId = layer.id;
+      state.tool = 'move';
+      const tb = state.container?.querySelector('.ge-toolbar');
+      if (tb) tb.querySelectorAll('.ge-tool-btn').forEach(b => b.classList.toggle('active', b.dataset.tool === 'move'));
+      renderLayerPanel();
+      composite();
+      uiModule.showToast('Pasted as new layer');
+    }
+
+    // Check internal clipboard first (from Ctrl+C lasso/wand).
+    if (state.internalClipboard) {
+      e.preventDefault();
+      e.stopImmediatePropagation();
+      pasteAsLayer(state.internalClipboard, 'Pasted Selection');
+      return;
+    }
+
+    // Fall back to system clipboard.
+    const items = e.clipboardData?.items;
+    if (!items) return;
+    for (const item of items) {
+      if (!item.type.startsWith('image/')) continue;
+      e.preventDefault();
+      e.stopImmediatePropagation();
+      const blob = item.getAsFile();
+      const url = URL.createObjectURL(blob);
+      const img = new Image();
+      img.onload = () => { pasteAsLayer(img, 'Pasted'); URL.revokeObjectURL(url); };
+      img.src = url;
+      break;
+    }
+  }, true);  // capture phase so we beat chat input
+
+  // ── Drag-and-drop ──
+  // Visual drop-zone overlay appears mid-drag; routes via
+  // handleImportedImage so the import respects canvas resizing rules
+  // + saves history (same path as the toolbar Import button).
+  const dropZone = container;
+  if (!dropZone) return;
+  let dragDepth = 0;
+  const hasFileType = (dt) => dt && Array.from(dt.types || []).some(t => t === 'Files');
+  const showOverlay = () => {
+    if (!state.editorOpen) return;
+    let ov = dropZone.querySelector('.ge-drop-overlay');
+    if (!ov) {
+      ov = document.createElement('div');
+      ov.className = 'ge-drop-overlay';
+      ov.innerHTML = '<div class="ge-drop-overlay-msg">Drop image to add as new layer</div>';
+      dropZone.appendChild(ov);
+    }
+    ov.style.display = '';
+  };
+  const hideOverlay = () => {
+    const ov = dropZone.querySelector('.ge-drop-overlay');
+    if (ov) ov.style.display = 'none';
+  };
+  dropZone.addEventListener('dragenter', (e) => {
+    if (!state.editorOpen || !hasFileType(e.dataTransfer)) return;
+    e.preventDefault();
+    dragDepth++;
+    showOverlay();
+  });
+  dropZone.addEventListener('dragover', (e) => {
+    if (!state.editorOpen || !hasFileType(e.dataTransfer)) return;
+    e.preventDefault();
+    e.dataTransfer.dropEffect = 'copy';
+  });
+  dropZone.addEventListener('dragleave', () => {
+    if (!state.editorOpen) return;
+    dragDepth = Math.max(0, dragDepth - 1);
+    if (dragDepth === 0) hideOverlay();
+  });
+  dropZone.addEventListener('drop', (e) => {
+    if (!state.editorOpen) return;
+    dragDepth = 0;
+    hideOverlay();
+    const files = Array.from(e.dataTransfer?.files || []).filter(f => f.type.startsWith('image/'));
+    if (!files.length) return;
+    e.preventDefault();
+    e.stopPropagation();
+    for (const f of files) {
+      const url = URL.createObjectURL(f);
+      const img = new Image();
+      img.onload = () => { handleImportedImage(img); URL.revokeObjectURL(url); };
+      img.onerror = () => URL.revokeObjectURL(url);
+      img.src = url;
+    }
+  });
+}

package/dist/web/static/js/editor/composite-helpers.js

@@ -0,0 +1,83 @@
+/**
+ * Pure composite helpers — flatten a layer list into a single canvas
+ * for thumbnails / merged-mask use.
+ *
+ * Both helpers are stateless: the caller passes everything they need
+ * (layer list, canvas dimensions, an offsets lookup). The legacy
+ * gallery editor's module-level functions wrap these with their own
+ * state.
+ */
+
+/**
+ * Cheap downscaled preview composited from all visible layers.
+ * Returns a JPEG dataURL, or null when there's nothing to draw.
+ *
+ * @param {Array<{visible: boolean, opacity: number, id: string, canvas: HTMLCanvasElement}>} layers
+ * @param {number} imgW            Document width in canvas pixels.
+ * @param {number} imgH            Document height in canvas pixels.
+ * @param {Map<string,{x:number,y:number}>} offsets  Layer offsets, keyed by id.
+ * @param {number} maxDim          Longest-edge target in CSS pixels.
+ * @param {number} quality         JPEG quality 0..1.
+ * @returns {string|null}
+ */
+export function buildThumbnail(layers, imgW, imgH, offsets, maxDim, quality = 0.6) {
+  if (!imgW || !imgH) return null;
+  try {
+    const scale = Math.min(1, maxDim / Math.max(imgW, imgH));
+    const tw = Math.max(1, Math.round(imgW * scale));
+    const th = Math.max(1, Math.round(imgH * scale));
+    const c = document.createElement('canvas');
+    c.width = tw; c.height = th;
+    const ctx = c.getContext('2d');
+    for (const layer of layers) {
+      if (!layer.visible) continue;
+      ctx.globalAlpha = layer.opacity;
+      const off = offsets.get(layer.id) || { x: 0, y: 0 };
+      ctx.drawImage(
+        layer.canvas,
+        off.x * scale, off.y * scale,
+        layer.canvas.width * scale, layer.canvas.height * scale,
+      );
+    }
+    ctx.globalAlpha = 1;
+    return c.toDataURL('image/jpeg', quality);
+  } catch (_) {
+    return null;
+  }
+}
+
+
+/**
+ * Union of every visible mask sub-layer across `layers`, rendered as a
+ * binary white canvas the size of the document.
+ *
+ * `lighter` composite = additive — overlapping pixels stay clamped at
+ * 255, so wherever any mask painted, the result is solid white.
+ * Returns null when no mask layer contributed any pixels (so the caller
+ * can early-out cleanly).
+ *
+ * @param {Array<{masks?: Array<{visible: boolean, canvas: HTMLCanvasElement}>}>} layers
+ * @param {number} imgW
+ * @param {number} imgH
+ * @returns {HTMLCanvasElement|null}
+ */
+export function buildMergedMaskCanvas(layers, imgW, imgH) {
+  if (!imgW || !imgH) return null;
+  const out = document.createElement('canvas');
+  out.width = imgW;
+  out.height = imgH;
+  const ctx = out.getContext('2d');
+  ctx.globalCompositeOperation = 'lighter';
+  let anyMask = false;
+  for (const ly of layers) {
+    if (!ly.masks || !ly.masks.length) continue;
+    for (const mk of ly.masks) {
+      if (!mk.visible) continue;
+      if (!mk.canvas || !mk.canvas.width || !mk.canvas.height) continue;
+      ctx.drawImage(mk.canvas, 0, 0);
+      anyMask = true;
+    }
+  }
+  ctx.globalCompositeOperation = 'source-over';
+  return anyMask ? out : null;
+}