@fraziym/axoniz 0.1.0

package/dist/web/static/js/editor/ai-models.js

@@ -0,0 +1,273 @@
+/**
+ * AI model dropdown loader — fetches available model endpoints from
+ * the backend and populates the editor's three model-select surfaces:
+ *
+ *   #ge-ai-model     — global Gen picker
+ *   #ge-ai-inpaint   — inpaint picker
+ *   select.ge-tool-model[data-ge-tool-model="…"]
+ *                    — per-tool pickers (harmonize / upscale / style /
+ *                      sharpen / etc.)
+ *
+ * Each model is filtered through a small capability classifier so the
+ * Gen dropdown only sees text-to-image models, the inpaint dropdown
+ * only sees image+mask edit models, and the per-tool dropdowns get
+ * everything img2img-capable.
+ *
+ * Every picker ends with a "+ Serve a model in Cookbook…" sentinel —
+ * choosing it opens Cookbook → Serve filtered to image models, then
+ * reverts the picker to its prior value (so it's an action, not a
+ * selectable model).
+ *
+ * @param {{
+ *   container:              HTMLElement,
+ *   apiBase:                string,
+ *   openCookbookForImg2img: () => void,
+ * }} deps
+ */
+import { state } from './state.js';
+import { sortModelIds } from '../modelSort.js';
+
+// Heuristic classifier on a model id + endpoint name. A model can be:
+//   - gen: text-to-image generation
+//   - inpaint: image+mask edit (inpaint / img2img)
+// Some models do only one (e.g. dall-e-3 = gen-only, no edits API).
+function modelCaps(modelId, endpointName, endpointType) {
+  const id = (modelId || '').toLowerCase();
+  const name = (endpointName || '').toLowerCase();
+  const type = (endpointType || '').toLowerCase();
+  // Reject anything obviously text-only.
+  const textOnly = /(?:^|[/\-_:])(gpt-?[345]|gpt-oss|claude|llama|qwen[^-]*chat|chat$|instruct$|coder)/i;
+  if (textOnly.test(id) && !/image/i.test(id)) return { gen: false, inpaint: false };
+  // OpenAI image family.
+  if (/dall-e-3/.test(id))    return { gen: true,  inpaint: false };
+  if (/dall-e-2/.test(id))    return { gen: true,  inpaint: true  };
+  if (/gpt-image/.test(id))   return { gen: true,  inpaint: true  };
+  // Diffusion families — most generic SD/SDXL/Flux base models
+  // support both via diffusers.
+  if (/(?:^|[/\-_])(?:sd-?xl|sdxl|sd3|sd-|stable[\s-]*diffusion|flux|playground|pixart|kandinsky)/i.test(id)) {
+    const isInpaintModel = /inpaint|edit|fill/i.test(id) || /inpaint|edit|fill/i.test(name);
+    return { gen: !isInpaintModel || /base/i.test(id), inpaint: true };
+  }
+  // Self-hosted diffusion server: model id often matches the repo
+  // name; trust the endpoint name hint.
+  if (type === 'image') {
+    if (/inpaint|edit|fill/i.test(name)) return { gen: false, inpaint: true };
+    return { gen: true, inpaint: true };
+  }
+  if (/inpaint|edit|fill/i.test(name)) return { gen: false, inpaint: true };
+  if (/diffus|flux|sd|image/i.test(name)) return { gen: true, inpaint: true };
+  // Editor image tools should be conservative. Unknown LLM/chat models
+  // do not belong in image generation or inpaint pickers.
+  return { gen: false, inpaint: false };
+}
+
+export function wireAIModelSelectors({ container, apiBase, openCookbookForImg2img }) {
+  // Delegated handler for the "+ Serve a model in Cookbook…" sentinel
+  // option — catches clicks regardless of whether loadAIModels has
+  // rewired the individual select yet and survives any innerHTML
+  // reset later.
+  container.addEventListener('change', (e) => {
+    const sel = e.target.closest('select');
+    if (!sel) return;
+    if (sel.value !== '__serve_cookbook__') return;
+    // Revert to the previous selection so the sentinel isn't "stuck".
+    const prev = sel._prevServeValue ?? '';
+    sel.value = prev;
+    openCookbookForImg2img();
+  });
+  // Track prior value so we can restore it after the sentinel fires.
+  container.addEventListener('focus', (e) => {
+    const sel = e.target.closest('select');
+    if (sel && sel.value !== '__serve_cookbook__') sel._prevServeValue = sel.value;
+  }, true);
+
+  const aiGenSelect = document.getElementById('ge-ai-model');
+  const aiInpaintSelect = document.getElementById('ge-ai-inpaint');
+  // The global Gen model dropdown was removed from the editor topbar;
+  // only bail if there's nothing to populate at all (neither the Gen
+  // select nor the inpaint select nor any per-tool select).
+  if (!aiGenSelect && !aiInpaintSelect &&
+      !document.querySelector('select.ge-tool-model')) return;
+
+  async function loadAIModels(opts = {}) {
+    try {
+      const selectBaseUrl = opts.selectBaseUrl || '';
+      const prevGenValue = aiGenSelect?.value || '';
+      const prevInpaintValue = aiInpaintSelect?.value || '';
+      const res = await fetch(`${apiBase}/api/model-endpoints`);
+      const endpoints = await res.json();
+      if (aiGenSelect) aiGenSelect.innerHTML = '<option value="">None</option>';
+      if (aiInpaintSelect) aiInpaintSelect.innerHTML = '<option value="">Auto</option>';
+      const perToolSelects = Array.from(document.querySelectorAll('select.ge-tool-model'));
+      for (const ts of perToolSelects) ts.innerHTML = '<option value="">Auto</option>';
+      let firstGen = null;
+      let firstInpaint = null;
+      let selectedGen = null;
+      let selectedInpaint = null;
+      for (const ep of endpoints) {
+        if (!ep.is_enabled) continue;
+        const hasListedModels = Array.isArray(ep.models) && ep.models.length;
+        const models = hasListedModels ? sortModelIds(ep.models) : [''];
+        const isImageEndpoint = (ep.model_type || '').toLowerCase() === 'image';
+        // Image/inpaint endpoints can be called by URL even when their
+        // /models cache is still empty, so don't strand a freshly served
+        // Cookbook model as "(offline)" in the editor picker.
+        const epUsable = !!ep.online || isImageEndpoint;
+        for (const modelId of models) {
+          const caps = modelCaps(modelId || ep.name, ep.name, ep.model_type);
+          if (!caps.gen && !caps.inpaint) continue;
+          // Encode "<base_url>::<model_id>" so the value carries both pieces.
+          const value = `${ep.base_url}::${modelId}`;
+          const shortModel = modelId ? String(modelId).split('/').pop() : (ep.name || ep.base_url);
+          const epHint = modelId && ep.name && ep.name !== modelId ? ` · ${ep.name}` : '';
+          const label = `${shortModel}${epHint}${epUsable ? '' : ' (offline)'}`;
+          if (caps.gen && aiGenSelect) {
+            const opt = document.createElement('option');
+            opt.value = value;
+            opt.textContent = label;
+            opt.disabled = !epUsable;
+            aiGenSelect.appendChild(opt);
+            if (epUsable && !firstGen) firstGen = value;
+            if (epUsable && selectBaseUrl && ep.base_url === selectBaseUrl && !selectedGen) selectedGen = value;
+          }
+          if (caps.inpaint && aiInpaintSelect) {
+            const opt = document.createElement('option');
+            opt.value = value;
+            opt.textContent = label;
+            opt.disabled = !epUsable;
+            aiInpaintSelect.appendChild(opt);
+            if (epUsable && selectBaseUrl && ep.base_url === selectBaseUrl && !selectedInpaint) selectedInpaint = value;
+            // Prefer dedicated inpaint/edit models for default selection.
+            if (epUsable && !firstInpaint && (!modelId || /inpaint|edit|fill|gpt-image/i.test(modelId) || /inpaint|edit|fill/i.test(ep.name || ''))) {
+              firstInpaint = value;
+            }
+          }
+          // Per-tool selectors get every img2img-capable entry. Both
+          // caps.inpaint AND caps.gen models work for harmonize /
+          // style / upscale (anything that can do img2img).
+          if (caps.inpaint || caps.gen) {
+            for (const ts of perToolSelects) {
+              const opt = document.createElement('option');
+              opt.value = value;
+              opt.textContent = label;
+              opt.disabled = !epUsable;
+              ts.appendChild(opt);
+            }
+          }
+        }
+      }
+      const hasValue = (sel, value) => !!value && [...sel.options].some(o => o.value === value);
+      if (aiGenSelect) {
+        if (selectedGen) aiGenSelect.value = selectedGen;
+        else if (hasValue(aiGenSelect, prevGenValue)) aiGenSelect.value = prevGenValue;
+        else if (firstGen) aiGenSelect.value = firstGen;
+      }
+      if (aiInpaintSelect) {
+        if (selectedInpaint) aiInpaintSelect.value = selectedInpaint;
+        else if (hasValue(aiInpaintSelect, prevInpaintValue)) aiInpaintSelect.value = prevInpaintValue;
+        else if (firstInpaint) aiInpaintSelect.value = firstInpaint;
+      }
+      // Append the "Serve a model in Cookbook…" sentinel at the
+      // bottom of every model dropdown.
+      const appendServeSentinel = (sel) => {
+        const sep = document.createElement('option');
+        sep.disabled = true;
+        sep.textContent = '──────────';
+        sel.appendChild(sep);
+        const serveOpt = document.createElement('option');
+        serveOpt.value = '__serve_cookbook__';
+        serveOpt.textContent = '+ Serve a model in Cookbook…';
+        sel.appendChild(serveOpt);
+      };
+      for (const ts of perToolSelects) appendServeSentinel(ts);
+      if (aiGenSelect) appendServeSentinel(aiGenSelect);
+      if (aiInpaintSelect) appendServeSentinel(aiInpaintSelect);
+      // Wire the sentinel on the Gen + Inpaint selects too.
+      const wireServeSentinel = (sel) => {
+        if (!sel) return;
+        let prev = sel.value;
+        sel.addEventListener('change', () => {
+          if (sel.value === '__serve_cookbook__') {
+            sel.value = prev;
+            openCookbookForImg2img();
+            return;
+          }
+          prev = sel.value;
+        });
+      };
+      wireServeSentinel(aiGenSelect);
+      wireServeSentinel(aiInpaintSelect);
+      // Restore each per-tool selection from localStorage.
+      for (const ts of perToolSelects) {
+        const key = 'ge-tool-model-' + ts.dataset.geToolModel;
+        try {
+          const saved = localStorage.getItem(key);
+          if (saved && [...ts.options].some(o => o.value === saved)) {
+            ts.value = saved;
+          }
+        } catch {}
+        let prevValue = ts.value;
+        ts.addEventListener('change', () => {
+          if (ts.value === '__serve_cookbook__') {
+            ts.value = prevValue;
+            openCookbookForImg2img();
+            return;
+          }
+          prevValue = ts.value;
+          try { localStorage.setItem(key, ts.value); } catch {}
+        });
+      }
+    } catch (e) {
+      // Fetch failed — still give the user the affordance to set up
+      // a model. Otherwise the dropdown shows only "Auto" with no
+      // hint about what to do next.
+      const fallback = '<option value="">Auto</option><option value="" disabled>──────────</option><option value="__serve_cookbook__">+ Serve a model in Cookbook…</option>';
+      if (aiGenSelect) aiGenSelect.innerHTML = fallback;
+      if (aiInpaintSelect) aiInpaintSelect.innerHTML = fallback;
+      document.querySelectorAll('select.ge-tool-model').forEach(ts => { ts.innerHTML = fallback; });
+      const wireServe = (sel) => {
+        if (!sel) return;
+        let prev = sel.value;
+        sel.addEventListener('change', () => {
+          if (sel.value === '__serve_cookbook__') {
+            sel.value = prev;
+            openCookbookForImg2img();
+            return;
+          }
+          prev = sel.value;
+        });
+      };
+      wireServe(aiGenSelect);
+      wireServe(aiInpaintSelect);
+      document.querySelectorAll('select.ge-tool-model').forEach(wireServe);
+    }
+  }
+  loadAIModels();
+  const onModelEndpointsUpdated = (e) => {
+    if (!container.isConnected) {
+      window.removeEventListener('ge:model-endpoints-updated', onModelEndpointsUpdated);
+      return;
+    }
+    loadAIModels({ selectBaseUrl: e.detail?.baseUrl || '' });
+  };
+  window.addEventListener('ge:model-endpoints-updated', onModelEndpointsUpdated);
+  // Re-fetch the model list when the user opens the inpaint dropdown,
+  // so a model served via Cookbook mid-edit shows up without having to
+  // close and reopen the editor. Debounced to one refresh per 3s so
+  // rapid open/close doesn't hammer the endpoint. Preserves the
+  // current selection across the reload.
+  let _lastModelRefresh = 0;
+  const refreshOnOpen = (e) => {
+    const sel = e.target.closest('#ge-ai-inpaint, select.ge-tool-model');
+    if (!sel) return;
+    const now = Date.now();
+    if (now - _lastModelRefresh < 3000) return;
+    _lastModelRefresh = now;
+    const keep = sel.value;
+    loadAIModels().then(() => {
+      // Restore the prior selection if it still exists.
+      if ([...sel.options].some(o => o.value === keep)) sel.value = keep;
+    });
+  };
+  container.addEventListener('mousedown', refreshOnOpen, true);
+}

package/dist/web/static/js/editor/ai-rembg.js

@@ -0,0 +1,230 @@
+/**
+ * Background Remove (rembg) + Sharpen wiring + the live edge-cleanup
+ * tuner that runs on the most-recent rembg cutout.
+ *
+ *   rembg-run button: flatten + POST to /api/image/remove-bg with an
+ *     optional hint_mask if the user has a wand/lasso selection
+ *     active. After the new layer lands, hides every previously-
+ *     visible layer so the cutout reads cleanly, and binds the
+ *     live-tuner to the new layer.
+ *
+ *   Live edge-cleanup tuner: snapshots the pristine cutout the
+ *     moment it lands; subsequent feather/grow slider tweaks
+ *     rebuild the layer's alpha from that snapshot WITHOUT
+ *     re-running the model.
+ *      - Grow > 0 → blur snap alpha, threshold low (32) → grow.
+ *      - Grow < 0 → blur snap alpha, threshold high (200) → shrink.
+ *      - Feather > 0 → blur the whole layer (alpha + RGB) so the
+ *        edge softens AND the residual color fringe from the
+ *        original background gets blurred away.
+ *
+ *   Sharpen: small slider + button; just calls _applyImageTool
+ *     against /api/image/sharpen.
+ *
+ *   buildSelectionHintMask: pure-ish utility — returns a base64 PNG
+ *     (no data: prefix) of the active wand or lasso selection, or
+ *     null. Returned so other wand-rembg call sites can use it.
+ *
+ * @param {{
+ *   applyImageTool:             (endpoint, payload, layerName, btn, opts?) => Promise<void>,
+ *   openCookbookForDependency:  (pkg: string) => void,
+ *   composite:                  () => void,
+ *   renderLayerPanel:           () => void,
+ *   uiModule:                   object,
+ * }} deps
+ *
+ * @returns {{ buildSelectionHintMask: () => string | null }}
+ */
+import { state } from './state.js';
+
+export function wireRembgAndSharpen({
+  applyImageTool, openCookbookForDependency,
+  composite, renderLayerPanel, uiModule,
+}) {
+  // ── Sharpen ──
+  const sharpenPrev = document.getElementById('ge-sharpen-preview');
+  if (sharpenPrev) sharpenPrev.style.opacity = '0.5';
+  document.getElementById('ge-sharpen-amount')?.addEventListener('input', (e) => {
+    document.getElementById('ge-sharpen-label').textContent = e.target.value + '%';
+    if (sharpenPrev) sharpenPrev.style.opacity = (parseInt(e.target.value, 10) / 100).toFixed(2);
+  });
+  document.getElementById('ge-sharpen-run')?.addEventListener('click', () => {
+    const amount = parseInt(document.getElementById('ge-sharpen-amount')?.value || '50');
+    applyImageTool('/api/image/sharpen', { amount }, 'Sharpened', document.getElementById('ge-sharpen-run'));
+  });
+
+  // ── Bg Remove ──
+  document.getElementById('ge-rembg-install-link')?.addEventListener('click', () => {
+    openCookbookForDependency('rembg');
+  });
+  document.getElementById('ge-rembg-run')?.addEventListener('click', async () => {
+    const payload = {};
+    const hint = buildSelectionHintMask();
+    if (hint) payload.hint_mask = hint;
+    // NB: edge_feather / edge_grow are applied CLIENT-side so the
+    // sliders can re-tune the cutout without re-running the model.
+    const btn = document.getElementById('ge-rembg-run');
+    const before = state.layers.length;
+    // Snapshot which layers were visible BEFORE the run so we know
+    // which to hide after a successful cutout.
+    const prevVisible = state.layers.filter(l => l.visible).map(l => l.id);
+    await applyImageTool('/api/image/remove-bg', payload, 'BG Removed', btn);
+    // applyImageTool finishes after fetch but the new layer is added
+    // inside img.onload (one tick later). Poll for up to 60 frames
+    // (~1s) for the new layer to appear before we auto-hide.
+    let frames = 0;
+    while (state.layers.length <= before && frames < 60) {
+      await new Promise(r => requestAnimationFrame(r));
+      frames++;
+    }
+    if (state.layers.length > before) {
+      const newLayer = state.layers[state.layers.length - 1];
+      bindRembgLiveTuner(newLayer);
+      // Auto-hide underlying layers so the user sees just the
+      // cutout — the eye toggles back on if they re-enable manually.
+      for (const layer of state.layers) {
+        if (prevVisible.includes(layer.id) && layer.id !== newLayer.id) {
+          layer.visible = false;
+        }
+      }
+      composite();
+      renderLayerPanel();
+    }
+    // Reset sliders so the new cutout starts clean.
+    const f = document.getElementById('ge-rembg-feather');
+    const g = document.getElementById('ge-rembg-grow');
+    if (f) { f.value = 0; document.getElementById('ge-rembg-feather-label').textContent = '0px'; syncRembgFeather(0); }
+    if (g) { g.value = 0; document.getElementById('ge-rembg-grow-label').textContent = '0px'; syncRembgGrow(0); }
+  });
+
+  // ── Live edge-cleanup tuner ──
+  // Snapshots the pristine cutout the moment it lands; slider tweaks
+  // rebuild alpha from that snapshot.
+  function bindRembgLiveTuner(layer) {
+    if (!layer) return;
+    const w = layer.canvas.width, h = layer.canvas.height;
+    const snap = document.createElement('canvas');
+    snap.width = w; snap.height = h;
+    snap.getContext('2d').drawImage(layer.canvas, 0, 0);
+    state.rembgLiveLayer = layer;
+    state.rembgLiveSnap = snap;
+    rembgApplyEdgeNow();  // initial pass (no-op at 0/0)
+  }
+  let rembgRaf = null;
+  function scheduleRembgApply() {
+    if (rembgRaf) return;
+    rembgRaf = requestAnimationFrame(() => { rembgRaf = null; rembgApplyEdgeNow(); });
+  }
+  function rembgApplyEdgeNow() {
+    if (!state.rembgLiveLayer || !state.rembgLiveSnap) return;
+    const feather = parseInt(document.getElementById('ge-rembg-feather')?.value || '0', 10);
+    const grow = parseInt(document.getElementById('ge-rembg-grow')?.value || '0', 10);
+    const layer = state.rembgLiveLayer;
+    const snap = state.rembgLiveSnap;
+    const w = snap.width, h = snap.height;
+    const lctx = layer.ctx;
+
+    // 1) Start fresh from the pristine cutout snapshot.
+    lctx.clearRect(0, 0, w, h);
+    lctx.drawImage(snap, 0, 0);
+
+    // 2) Edge ±N — dilate / erode alpha via blur+threshold:
+    //      grow > 0 → low threshold (32) → halo counts as opaque → grows.
+    //      grow < 0 → high threshold (200) → only solid interior → shrinks.
+    //    RGB is kept; only alpha is replaced.
+    if (grow !== 0) {
+      const blurC = document.createElement('canvas');
+      blurC.width = w; blurC.height = h;
+      const bctx = blurC.getContext('2d');
+      bctx.filter = `blur(${Math.abs(grow)}px)`;
+      bctx.drawImage(snap, 0, 0);
+      bctx.filter = 'none';
+      const blurred = bctx.getImageData(0, 0, w, h).data;
+      const layerData = lctx.getImageData(0, 0, w, h);
+      const out = layerData.data;
+      const thr = grow > 0 ? 32 : 200;
+      for (let i = 0; i < out.length; i += 4) {
+        out[i + 3] = blurred[i + 3] >= thr ? 255 : 0;
+      }
+      lctx.putImageData(layerData, 0, 0);
+    }
+
+    // 3) Feather softens whatever edge we have now. Blur the entire
+    //    layer (alpha + RGB) — alpha gets smooth falloff, RGB gets a
+    //    faint blur at the edge which actually helps hide residual
+    //    colour fringing from the original background.
+    if (feather > 0) {
+      const fC = document.createElement('canvas');
+      fC.width = w; fC.height = h;
+      const fctx = fC.getContext('2d');
+      fctx.filter = `blur(${feather}px)`;
+      fctx.drawImage(layer.canvas, 0, 0);
+      fctx.filter = 'none';
+      lctx.clearRect(0, 0, w, h);
+      lctx.drawImage(fC, 0, 0);
+    }
+    composite();
+  }
+
+  // ── Slider preview swatches + wiring ──
+  const rembgFeatherPrev = document.getElementById('ge-rembg-feather-preview');
+  const rembgGrowPrev = document.getElementById('ge-rembg-grow-preview');
+  function syncRembgFeather(v) {
+    if (!rembgFeatherPrev) return;
+    const inner = Math.max(0, 50 - v * 2.5);
+    rembgFeatherPrev.style.background = `radial-gradient(circle, var(--fg) 0%, var(--fg) ${inner}%, transparent 75%)`;
+  }
+  function syncRembgGrow(v) {
+    if (!rembgGrowPrev) return;
+    // -10..+10 → scale 0.6 .. 1.4 so the swatch visibly grows/shrinks.
+    const s = 1 + v * 0.04;
+    rembgGrowPrev.style.transform = `scale(${s})`;
+    rembgGrowPrev.style.background = v < 0 ? 'color-mix(in srgb, var(--fg) 40%, transparent)' : 'var(--fg)';
+  }
+  syncRembgFeather(2);
+  syncRembgGrow(0);
+  document.getElementById('ge-rembg-feather')?.addEventListener('input', (e) => {
+    const v = parseInt(e.target.value, 10);
+    document.getElementById('ge-rembg-feather-label').textContent = v + 'px';
+    syncRembgFeather(v);
+    scheduleRembgApply();
+  });
+  document.getElementById('ge-rembg-grow')?.addEventListener('input', (e) => {
+    const v = parseInt(e.target.value, 10);
+    document.getElementById('ge-rembg-grow-label').textContent = (v >= 0 ? '+' : '') + v + 'px';
+    syncRembgGrow(v);
+    scheduleRembgApply();
+  });
+
+  // ── Selection-hint mask builder (used here + by wand-rembg) ──
+  // Full-image white-on-transparent mask PNG (base64, no `data:`
+  // prefix) of whichever selection is active — wand first, lasso
+  // second. Returns null if neither has a selection.
+  function buildSelectionHintMask() {
+    const w = state.imgWidth, h = state.imgHeight;
+    if (state.wandMask && state.wandLayerId) {
+      const off = state.layerOffsets.get(state.wandLayerId) || { x: 0, y: 0 };
+      const c = document.createElement('canvas');
+      c.width = w; c.height = h;
+      c.getContext('2d').drawImage(state.wandMask, off.x, off.y);
+      return c.toDataURL('image/png').split(',')[1];
+    }
+    if (state.lassoPoints.length >= 3 && !state.lassoActive) {
+      const c = document.createElement('canvas');
+      c.width = w; c.height = h;
+      const ctx = c.getContext('2d');
+      ctx.fillStyle = '#fff';
+      ctx.beginPath();
+      ctx.moveTo(state.lassoPoints[0].x, state.lassoPoints[0].y);
+      for (let i = 1; i < state.lassoPoints.length; i++) {
+        ctx.lineTo(state.lassoPoints[i].x, state.lassoPoints[i].y);
+      }
+      ctx.closePath();
+      ctx.fill();
+      return c.toDataURL('image/png').split(',')[1];
+    }
+    return null;
+  }
+
+  return { buildSelectionHintMask };
+}

package/dist/web/static/js/editor/ai-tool-runner.js

@@ -0,0 +1,147 @@
+/**
+ * Shared AI-tool runner. Used by Sharpen / Harmonize / Upscale / Style /
+ * Bg-Remove / etc. — every tool that flattens the document, POSTs the
+ * PNG to a server-side image endpoint, and drops the result back in
+ * as a new layer.
+ *
+ * Handles all the orchestration around the request:
+ *
+ *  - Button busy state: swap label for "<verbing>…" + whirlpool
+ *    spinner, lock width so the button doesn't visually jump.
+ *  - Endpoint+model selection from the tool's own picker (or the
+ *    global fallback) so the backend knows which model to invoke.
+ *  - Response handling: decode the returned PNG, push it as a new
+ *    layer, save state, composite, refresh the layer panel.
+ *  - Error reporting: surface failures via toast. Detects "needs
+ *    img2img server" and "package not installed" failure modes and
+ *    surfaces an action-toast that opens Cookbook to fix.
+ *
+ * @param {{
+ *   flatten:                    () => HTMLCanvasElement,
+ *   saveState:                  (label?: string) => void,
+ *   createLayer:                (name: string, w: number, h: number) => object,
+ *   composite:                  () => void,
+ *   renderLayerPanel:           () => void,
+ *   deriveBusyLabel:            (layerName: string) => string,
+ *   getSelectedAIEndpoint:      (type: string | null) => { endpoint?: string, model?: string },
+ *   openCookbookForDependency:  (pkg: string) => void,
+ *   openCookbookForImg2img:     () => void,
+ *   spinnerModule:              object,
+ *   uiModule:                   object | null,
+ * }} deps
+ *
+ * @returns {(endpoint: string, extraPayload: object, layerName: string, btn: HTMLButtonElement, opts?: { busyLabel?: string }) => Promise<void>}
+ */
+import { state } from './state.js';
+
+const KNOWN_DEPS = ['realesrgan', 'rembg'];
+
+export function createApplyImageTool({
+  flatten, saveState, createLayer, composite, renderLayerPanel,
+  deriveBusyLabel, getSelectedAIEndpoint,
+  openCookbookForDependency, openCookbookForImg2img,
+  spinnerModule, uiModule,
+}) {
+  return async function applyImageTool(endpoint, extraPayload, layerName, btn, opts) {
+    const origHTML = btn.innerHTML;
+    const origWidth = btn.offsetWidth;  // lock width so the button doesn't jump
+    btn.disabled = true;
+    btn.classList.add('ge-btn-processing');
+    btn.style.minWidth = origWidth + 'px';
+    // Swap label for a "<verbing>…" text + whirlpool while the
+    // request runs. Falls back to deriving a busy label from
+    // layerName when the caller didn't supply one.
+    const busyLabel = (opts && opts.busyLabel) || deriveBusyLabel(layerName);
+    btn.innerHTML = '';
+    let btnSpinner = null;
+    try {
+      btnSpinner = spinnerModule.create('', 'clean', 'whirlpool');
+      const sp = btnSpinner.createElement();
+      btn.appendChild(sp);
+      const txt = document.createElement('span');
+      txt.className = 'ge-btn-busy-label';
+      txt.textContent = busyLabel;
+      btn.appendChild(txt);
+      btnSpinner.start();
+    } catch { btn.textContent = busyLabel; }
+    // Tool-specific model picker — pulled from the per-tool select
+    // (harmonize/style) if available, otherwise the global
+    // fallback. Derived from the endpoint URL.
+    if (!extraPayload._endpoint) {
+      const m = /\/api\/image\/([\w-]+)/.exec(endpoint || '');
+      const type = m ? m[1].replace('upscale-ai', 'upscale').replace('remove-bg', 'rembg') : null;
+      const sel = getSelectedAIEndpoint(type);
+      if (sel.endpoint) extraPayload._endpoint = sel.endpoint;
+      if (sel.model && !extraPayload._model) extraPayload._model = sel.model;
+    }
+    try {
+      const flatCanvas = flatten();
+      const imageB64 = flatCanvas.toDataURL('image/png').split(',')[1];
+      const body = { image: imageB64, ...extraPayload };
+      const res = await fetch(endpoint, {
+        method: 'POST', credentials: 'same-origin',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+      });
+      if (!res.ok) {
+        let err = res.statusText;
+        try { const e = await res.json(); err = e.detail || e.error || err; } catch {}
+        throw new Error(err);
+      }
+      const data = await res.json();
+      if (data.error) throw new Error(data.error);
+      if (!data.image) throw new Error('No image returned');
+      const img = new Image();
+      img.onload = () => {
+        if (!state.editorOpen) return; // user closed mid-decode (v2 review HIGH-4)
+        saveState();
+        const layer = createLayer(layerName, state.imgWidth, state.imgHeight);
+        layer.ctx.drawImage(img, 0, 0);
+        state.layers.push(layer);
+        state.activeLayerId = layer.id;
+        composite();
+        renderLayerPanel();
+        if (uiModule) uiModule.showToast(layerName + ' complete', 4500);
+      };
+      img.onerror = () => { if (uiModule) uiModule.showToast('Failed to load result', 6000); };
+      img.src = 'data:image/png;base64,' + data.image;
+    } catch (e) {
+      // Detect known failure modes and surface an action-toast.
+      const msg = (e?.message || '').toLowerCase();
+      const needsImg2Img = (
+        msg.includes('img2img') ||
+        msg.includes('diffusion server') ||
+        msg.includes("doesn't expose")
+      );
+      let depMatch = null;
+      for (const pkg of KNOWN_DEPS) {
+        if (msg.includes(`${pkg} not installed`) || msg.includes(`no module named '${pkg}'`)) {
+          depMatch = pkg; break;
+        }
+      }
+      if (uiModule) {
+        if (depMatch && uiModule.showToast.length >= 2) {
+          uiModule.showToast(layerName + ' failed: ' + depMatch + ' is not installed on the server.', {
+            duration: 9000,
+            action: `Install ${depMatch}`,
+            onAction: () => openCookbookForDependency(depMatch),
+          });
+        } else if (needsImg2Img && uiModule.showToast.length >= 2) {
+          uiModule.showToast(layerName + ' failed: ' + e.message, {
+            duration: 9000,
+            action: 'Open Cookbook',
+            onAction: () => openCookbookForImg2img(),
+          });
+        } else {
+          uiModule.showToast(layerName + ' failed: ' + e.message, 6000);
+        }
+      }
+    } finally {
+      btn.disabled = false;
+      btn.classList.remove('ge-btn-processing');
+      try { btnSpinner?.destroy(); } catch {}
+      btn.innerHTML = origHTML;
+      btn.style.minWidth = '';
+    }
+  };
+}