@loupekit/sdk 0.1.0 → 0.2.0-next.1

package/dist/index.js

@@ -5,7 +5,9 @@ var STYLES = (
 :host { all: initial; }
 * { box-sizing: border-box; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif; }
 
-:root, .loupe {
+/* Custom properties must live on :host \u2014 inside the Shadow DOM, :root matches
+   nothing and no element carries a .loupe class, so they'd never resolve. */
+:host {
   --accent: #4a55d6;
   --pin: #ff5842;
   --ink: #16181f;
@@ -33,6 +35,17 @@ var STYLES = (
   font-family: ui-monospace, Menlo, monospace;
 }
 
+/* region selection (during drag) + active-comment outline */
+.selbox {
+  position: fixed; pointer-events: none; z-index: 2147483001; display: none;
+  border: 2px dashed var(--accent); background: rgba(74, 85, 214, 0.12); border-radius: 4px;
+}
+.region-box {
+  position: fixed; pointer-events: none; z-index: 2147483001; display: none;
+  border: 2px solid var(--pin); border-radius: 4px;
+  box-shadow: 0 0 0 2px rgba(255, 88, 66, .25), 0 4px 16px rgba(0,0,0,.25);
+}
+
 /* pins */
 .pin {
   position: fixed; pointer-events: auto; z-index: 2147483002;
@@ -62,6 +75,7 @@ var STYLES = (
   display: flex; align-items: center; gap: 6px;
 }
 .toolbar button:hover { background: #2b2f3b; color: #fff; }
+.toolbar button .ico { flex: none; display: block; }
 .toolbar button.on { background: var(--accent); color: #fff; }
 .toolbar .sep { width: 1px; height: 20px; background: #333846; margin: 0 2px; }
 .toolbar .brand { font-weight: 700; padding-left: 8px; padding-right: 4px; letter-spacing: -.01em; }
@@ -1916,6 +1930,50 @@ async function captureScreenshot(el2) {
     return void 0;
   }
 }
+async function captureRegionScreenshot(rect) {
+  try {
+    const scale = Math.min(window.devicePixelRatio || 1, 2);
+    const full = await domToPng(document.body, {
+      scale,
+      backgroundColor: getComputedStyle(document.body).backgroundColor || "#ffffff",
+      filter: (node) => {
+        if (!(node instanceof Element)) return true;
+        if (node.id === "loupe-root") return false;
+        if (node.hasAttribute("data-loupe-redact")) return false;
+        return true;
+      }
+    });
+    const bodyRect = document.body.getBoundingClientRect();
+    const redact = Array.from(document.querySelectorAll("[data-loupe-redact]")).map(
+      (n) => n.getBoundingClientRect()
+    );
+    return await cropRegion(full, rect, bodyRect.left, bodyRect.top, scale, redact);
+  } catch (err) {
+    console.warn("[loupe] region capture failed", err);
+    return void 0;
+  }
+}
+function cropRegion(dataUrl, rect, ox, oy, scale, redact) {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.onload = () => {
+      const sw = Math.max(1, Math.round(rect.w * scale));
+      const sh = Math.max(1, Math.round(rect.h * scale));
+      const canvas = document.createElement("canvas");
+      canvas.width = sw;
+      canvas.height = sh;
+      const ctx = canvas.getContext("2d");
+      ctx.drawImage(img, (rect.x - ox) * scale, (rect.y - oy) * scale, sw, sh, 0, 0, sw, sh);
+      ctx.fillStyle = "#0f0f14";
+      for (const r of redact) {
+        ctx.fillRect((r.left - rect.x) * scale, (r.top - rect.y) * scale, r.width * scale, r.height * scale);
+      }
+      resolve(canvas.toDataURL("image/png"));
+    };
+    img.onerror = reject;
+    img.src = dataUrl;
+  });
+}
 
 // src/store.ts
 var LocalStorageAdapter = class {
@@ -1971,56 +2029,63 @@ var LocalStorageAdapter = class {
 
 // src/http-adapter.ts
 var HttpAdapter = class {
-  constructor(base, user, userHmac) {
+  constructor(base, user, userHmac, extraHeaders, credentials) {
     this.base = base;
     this.user = user;
     this.userHmac = userHmac;
+    this.extraHeaders = extraHeaders;
+    this.credentials = credentials;
     this.base = base.replace(/\/$/, "");
   }
   headers() {
     const h = { "Content-Type": "application/json", "X-Loupe-User": this.user.id };
     if (this.userHmac) h["X-Loupe-Hmac"] = this.userHmac;
+    if (this.extraHeaders) Object.assign(h, this.extraHeaders);
     return h;
   }
+  /** Base fetch options shared by every request (credentials mode, if set). */
+  opts(init2) {
+    return this.credentials ? { credentials: this.credentials, ...init2 } : { ...init2 };
+  }
   async list(projectKey, url) {
     const q = new URLSearchParams({ projectKey, url });
-    const res = await fetch(`${this.base}/v1/comments?${q}`, { headers: this.headers() });
+    const res = await fetch(`${this.base}/v1/comments?${q}`, this.opts({ headers: this.headers() }));
     if (!res.ok) throw new Error(`list failed: ${res.status}`);
     return await res.json();
   }
   async save(comment) {
     if (comment.screenshot?.startsWith("data:")) {
       try {
-        const up = await fetch(`${this.base}/v1/blobs`, {
+        const up = await fetch(`${this.base}/v1/blobs`, this.opts({
           method: "POST",
           headers: this.headers(),
           body: JSON.stringify({ projectKey: comment.projectKey, data: comment.screenshot })
-        });
+        }));
         if (up.ok) comment = { ...comment, screenshot: (await up.json()).url };
       } catch {
       }
     }
-    const res = await fetch(`${this.base}/v1/comments`, {
+    const res = await fetch(`${this.base}/v1/comments`, this.opts({
       method: "POST",
       headers: this.headers(),
       body: JSON.stringify(comment)
-    });
+    }));
     if (!res.ok) throw new Error(`save failed: ${res.status}`);
     return await res.json();
   }
   async update(id, patch) {
-    const res = await fetch(`${this.base}/v1/comments/${encodeURIComponent(id)}`, {
+    const res = await fetch(`${this.base}/v1/comments/${encodeURIComponent(id)}`, this.opts({
       method: "PATCH",
       headers: this.headers(),
       body: JSON.stringify(patch)
-    });
+    }));
     if (!res.ok) throw new Error(`update failed: ${res.status}`);
   }
   async remove(id) {
-    const res = await fetch(`${this.base}/v1/comments/${encodeURIComponent(id)}`, {
+    const res = await fetch(`${this.base}/v1/comments/${encodeURIComponent(id)}`, this.opts({
       method: "DELETE",
       headers: this.headers()
-    });
+    }));
     if (!res.ok && res.status !== 404) throw new Error(`remove failed: ${res.status}`);
   }
 };
@@ -2039,14 +2104,16 @@ var LoupeApp = class {
     this.resolved = /* @__PURE__ */ new Map();
     /** comment.id → pin element. */
     this.pins = /* @__PURE__ */ new Map();
-    this.inspecting = false;
-    this.target = null;
+    this.mode = "off";
     this.targetOffset = { x: 0.5, y: 0.5 };
-    this.activeId = null;
+    this.pending = null;
+    this.dragStart = null;
+    /** region comment whose outline is currently highlighted (tracks scroll). */
+    this.activeRegionId = null;
     this.raf = 0;
     // ---- inspector ------------------------------------------------------------
     this.onMove = (e) => {
-      if (!this.inspecting) return;
+      if (this.mode !== "inspect") return;
       const target = this.pick(e.clientX, e.clientY);
       if (!target) {
         this.hl.style.display = "none";
@@ -2063,7 +2130,7 @@ var LoupeApp = class {
       this.hl.firstChild.textContent = target.tagName.toLowerCase() + (target.id ? "#" + target.id : "");
     };
     this.onClick = (e) => {
-      if (!this.inspecting) return;
+      if (this.mode !== "inspect") return;
       const target = this.pick(e.clientX, e.clientY);
       if (!target) return;
       e.preventDefault();
@@ -2073,16 +2140,50 @@ var LoupeApp = class {
         x: r.width ? clamp((e.clientX - r.left) / r.width) : 0.5,
         y: r.height ? clamp((e.clientY - r.top) / r.height) : 0.5
       };
-      this.target = target;
-      this.setInspecting(false);
-      this.openComposer(target, e.clientX, e.clientY);
+      this.setMode("off");
+      this.openComposer({ kind: "element", element: target }, e.clientX, e.clientY);
     };
     this.onKey = (e) => {
       if (e.key === "Escape") {
-        this.setInspecting(false);
+        this.cancelDrag();
+        this.setMode("off");
         this.closeComposer();
       }
     };
+    // ---- region ("free-size screenshot") selection ----------------------------
+    this.onRegionDown = (e) => {
+      if (this.mode !== "region" || e.button !== 0) return;
+      e.preventDefault();
+      e.stopPropagation();
+      this.dragStart = { x: e.clientX, y: e.clientY };
+      document.addEventListener("mousemove", this.onRegionMove, true);
+      document.addEventListener("mouseup", this.onRegionUp, true);
+      this.drawSelection(e.clientX, e.clientY);
+    };
+    this.onRegionMove = (e) => {
+      if (!this.dragStart) return;
+      e.preventDefault();
+      this.drawSelection(e.clientX, e.clientY);
+    };
+    this.onRegionUp = (e) => {
+      if (!this.dragStart) return;
+      e.preventDefault();
+      e.stopPropagation();
+      const start = this.dragStart;
+      this.cancelDrag();
+      const vp = {
+        x: Math.min(start.x, e.clientX),
+        y: Math.min(start.y, e.clientY),
+        w: Math.abs(e.clientX - start.x),
+        h: Math.abs(e.clientY - start.y)
+      };
+      if (vp.w < 8 || vp.h < 8) {
+        this.selbox.style.display = "none";
+        return;
+      }
+      this.setMode("off");
+      this.finishRegion(vp);
+    };
     /** Reposition every pin, re-resolving anchors whose element has gone. */
     this.position = () => {
       for (const c of this.comments) {
@@ -2094,6 +2195,18 @@ var LoupeApp = class {
           elx = r?.element ?? null;
           this.resolved.set(c.id, elx);
         }
+        if (c.kind === "region") {
+          const box = this.regionRect(c, elx);
+          if (box) {
+            const onScreen = box.x + box.w > 0 && box.x < window.innerWidth && box.y + box.h > 0 && box.y < window.innerHeight;
+            Object.assign(pin.style, { left: box.x + "px", top: box.y + "px", display: onScreen ? "grid" : "none" });
+            pin.classList.toggle("detached", !elx && !c.region?.rel);
+          } else {
+            pin.style.display = "none";
+            pin.classList.add("detached");
+          }
+          continue;
+        }
         if (elx) {
           const rect = elx.getBoundingClientRect();
           const px = rect.left + c.offset.x * rect.width;
@@ -2106,9 +2219,22 @@ var LoupeApp = class {
           pin.classList.add("detached");
         }
       }
+      if (this.activeRegionId) {
+        const c = this.comments.find((x) => x.id === this.activeRegionId);
+        const box = c && this.regionRect(c, this.resolved.get(c.id) ?? null);
+        if (box) {
+          Object.assign(this.regionBox.style, {
+            display: "block",
+            left: box.x + "px",
+            top: box.y + "px",
+            width: box.w + "px",
+            height: box.h + "px"
+          });
+        }
+      }
     };
     this.cfg = cfg;
-    this.store = cfg.apiBase ? new HttpAdapter(cfg.apiBase, cfg.user, cfg.userHmac) : new LocalStorageAdapter();
+    this.store = cfg.apiBase ? new HttpAdapter(cfg.apiBase, cfg.user, cfg.userHmac, cfg.headers, cfg.credentials) : new LocalStorageAdapter();
   }
   get url() {
     return location.pathname + location.search;
@@ -2119,7 +2245,7 @@ var LoupeApp = class {
     this.renderPins();
     this.renderPanel();
     this.observe();
-    if (this.cfg.autoOpen) this.setInspecting(true);
+    if (this.cfg.autoOpen) this.setMode("inspect");
   }
   // ---- DOM construction -----------------------------------------------------
   buildDom() {
@@ -2133,7 +2259,9 @@ var LoupeApp = class {
     this.overlay = el("div", "overlay");
     this.hl = el("div", "hl");
     this.hl.appendChild(el("span", "tip"));
-    this.overlay.appendChild(this.hl);
+    this.selbox = el("div", "selbox");
+    this.regionBox = el("div", "region-box");
+    this.overlay.append(this.hl, this.selbox, this.regionBox);
     this.shadow.appendChild(this.overlay);
     this.composer = el("div", "composer");
     this.shadow.appendChild(this.composer);
@@ -2147,14 +2275,55 @@ var LoupeApp = class {
     const brand = el("span", "brand", "\u25CE Loupe");
     const inspectBtn = el("button", "", "\u271B Inspect & comment");
     inspectBtn.dataset.role = "inspect";
-    inspectBtn.onclick = () => this.setInspecting(!this.inspecting);
+    inspectBtn.onclick = () => this.setMode(this.mode === "inspect" ? "off" : "inspect");
+    const regionBtn = el("button");
+    regionBtn.innerHTML = `${REGION_ICON}<span>Region shot</span>`;
+    regionBtn.dataset.role = "region";
+    regionBtn.title = "Drag a free-size box, screenshot it, and comment";
+    regionBtn.onclick = () => this.setMode(this.mode === "region" ? "off" : "region");
     const listBtn = el("button", "", "\u2630 Comments");
     this.countEl = el("span", "count", "0");
     listBtn.appendChild(this.countEl);
     listBtn.onclick = () => this.togglePanel();
-    bar.append(brand, sep(), inspectBtn, listBtn);
+    bar.append(brand, sep(), inspectBtn, regionBtn, listBtn);
     return bar;
   }
+  drawSelection(curX, curY) {
+    const s = this.dragStart;
+    Object.assign(this.selbox.style, {
+      display: "block",
+      left: Math.min(s.x, curX) + "px",
+      top: Math.min(s.y, curY) + "px",
+      width: Math.abs(curX - s.x) + "px",
+      height: Math.abs(curY - s.y) + "px"
+    });
+  }
+  cancelDrag() {
+    this.dragStart = null;
+    document.removeEventListener("mousemove", this.onRegionMove, true);
+    document.removeEventListener("mouseup", this.onRegionUp, true);
+  }
+  /** Capture the selected viewport rect, then open the composer for a region comment. */
+  async finishRegion(vp) {
+    const centerEl = this.pick(vp.x + vp.w / 2, vp.y + vp.h / 2);
+    let rel;
+    if (centerEl) {
+      const er = centerEl.getBoundingClientRect();
+      if (er.width > 0 && er.height > 0) {
+        rel = {
+          fx: (vp.x - er.left) / er.width,
+          fy: (vp.y - er.top) / er.height,
+          fw: vp.w / er.width,
+          fh: vp.h / er.height
+        };
+      }
+    }
+    const capture = this.cfg.captureRegion ?? captureRegionScreenshot;
+    const screenshot = await capture(vp);
+    this.selbox.style.display = "none";
+    const region = { x: vp.x + window.scrollX, y: vp.y + window.scrollY, w: vp.w, h: vp.h, rel };
+    this.openComposer({ kind: "region", region, element: centerEl, screenshot }, vp.x + vp.w, vp.y);
+  }
   /** elementFromPoint, ignoring our own UI. */
   pick(x, y) {
     const hitHl = this.hl.style.display;
@@ -2165,34 +2334,45 @@ var LoupeApp = class {
     if (elAt.id === "loupe-root" || elAt.closest?.("#loupe-root")) return null;
     return elAt;
   }
-  setInspecting(on) {
-    this.inspecting = on;
+  setMode(mode) {
+    this.mode = mode;
     this.hl.style.display = "none";
-    document.body.style.cursor = on ? "crosshair" : "";
-    const btn = this.toolbar.querySelector('[data-role="inspect"]');
-    btn.classList.toggle("on", on);
-    if (on) {
+    this.selbox.style.display = "none";
+    this.cancelDrag();
+    document.body.style.cursor = mode === "off" ? "" : "crosshair";
+    this.toolbar.querySelector('[data-role="inspect"]')?.classList.toggle("on", mode === "inspect");
+    this.toolbar.querySelector('[data-role="region"]')?.classList.toggle("on", mode === "region");
+    document.removeEventListener("mousemove", this.onMove, true);
+    document.removeEventListener("click", this.onClick, true);
+    document.removeEventListener("mousedown", this.onRegionDown, true);
+    if (mode === "off") return;
+    document.addEventListener("keydown", this.onKey, true);
+    this.closeComposer();
+    if (mode === "inspect") {
       document.addEventListener("mousemove", this.onMove, true);
       document.addEventListener("click", this.onClick, true);
-      document.addEventListener("keydown", this.onKey, true);
-      this.closeComposer();
-    } else {
-      document.removeEventListener("mousemove", this.onMove, true);
-      document.removeEventListener("click", this.onClick, true);
+    } else if (mode === "region") {
+      document.addEventListener("mousedown", this.onRegionDown, true);
     }
   }
   // ---- composer -------------------------------------------------------------
   openComposer(target, x, y) {
+    this.pending = target;
     const c = this.composer;
     c.innerHTML = "";
-    const label = el("div", "target", describe(target));
+    const label = el(
+      "div",
+      "target",
+      target.kind === "element" ? describe(target.element) : `Region \xB7 ${Math.round(target.region.w)}\xD7${Math.round(target.region.h)} px`
+    );
     const ta = el("textarea");
-    ta.placeholder = "What should change here?";
+    ta.placeholder = target.kind === "region" ? "What's the issue in this area?" : "What should change here?";
     const row = el("div", "row");
     const chk = el("label", "chk");
     const box = document.createElement("input");
     box.type = "checkbox";
-    box.checked = true;
+    box.checked = target.kind === "region" ? !!target.screenshot : true;
+    if (target.kind === "region" && !target.screenshot) box.disabled = true;
     chk.append(box, document.createTextNode("Attach screenshot"));
     const btns = el("div", "btns");
     const cancel = el("button", "ghost", "Cancel");
@@ -2214,7 +2394,7 @@ var LoupeApp = class {
   }
   closeComposer() {
     this.composer.style.display = "none";
-    this.target = null;
+    this.pending = null;
   }
   async submit(target, body, withShot) {
     if (!body) return;
@@ -2223,8 +2403,30 @@ var LoupeApp = class {
       saveBtn.disabled = true;
       saveBtn.textContent = "Saving\u2026";
     }
-    const capture = this.cfg.captureScreenshot ?? captureScreenshot;
-    const screenshot = withShot ? await capture(target) : void 0;
+    let anchor, context, offset;
+    let screenshot;
+    let region;
+    let anchoredEl = null;
+    if (target.kind === "element") {
+      const capture = this.cfg.captureScreenshot ?? captureScreenshot;
+      screenshot = withShot ? await capture(target.element) : void 0;
+      anchor = captureAnchor(target.element);
+      context = captureElementContext(target.element);
+      offset = this.targetOffset;
+      anchoredEl = target.element;
+    } else {
+      screenshot = withShot ? target.screenshot : void 0;
+      region = target.region;
+      offset = { x: 0, y: 0 };
+      if (target.element) {
+        anchor = captureAnchor(target.element);
+        context = captureElementContext(target.element);
+        anchoredEl = target.element;
+      } else {
+        anchor = regionAnchor(region);
+        context = { html: regionNote(region), styles: {} };
+      }
+    }
     const comment = {
       id: uid2(),
       projectKey: this.cfg.projectKey,
@@ -2232,15 +2434,17 @@ var LoupeApp = class {
       author: this.cfg.user,
       body,
       status: "open",
-      anchor: captureAnchor(target),
-      context: captureElementContext(target),
-      offset: this.targetOffset,
+      kind: target.kind,
+      anchor,
+      context,
+      offset,
+      region,
       screenshot,
       createdAt: (/* @__PURE__ */ new Date()).toISOString()
     };
     await this.store.save(comment);
     this.comments.push(comment);
-    this.resolved.set(comment.id, target);
+    this.resolved.set(comment.id, anchoredEl);
     this.closeComposer();
     this.renderPins();
     this.renderPanel();
@@ -2271,6 +2475,22 @@ var LoupeApp = class {
     this.countEl.textContent = String(this.comments.length);
     this.position();
   }
+  /**
+   * The current viewport rect for a region comment. Prefers the element-relative
+   * fractions (so it tracks reflow across viewports); falls back to the stored
+   * document coordinates minus scroll. Returns null if neither is available.
+   */
+  regionRect(c, elx) {
+    const rel = c.region?.rel;
+    if (elx && rel) {
+      const r = elx.getBoundingClientRect();
+      return { x: r.left + rel.fx * r.width, y: r.top + rel.fy * r.height, w: rel.fw * r.width, h: rel.fh * r.height };
+    }
+    if (c.region) {
+      return { x: c.region.x - window.scrollX, y: c.region.y - window.scrollY, w: c.region.w, h: c.region.h };
+    }
+    return null;
+  }
   observe() {
     const reposition = () => {
       cancelAnimationFrame(this.raf);
@@ -2387,7 +2607,23 @@ var LoupeApp = class {
     }
   }
   flash(id) {
+    const c = this.comments.find((x) => x.id === id);
     const pin = this.pins.get(id);
+    if (c?.kind === "region" && c.region) {
+      for (const p of this.pins.values()) p.classList.remove("active");
+      pin?.classList.add("active");
+      this.activeRegionId = id;
+      window.clearTimeout(this.regionTimer);
+      this.regionTimer = window.setTimeout(() => {
+        this.activeRegionId = null;
+        this.regionBox.style.display = "none";
+      }, 2400);
+      const elx2 = this.resolved.get(id);
+      if (elx2) elx2.scrollIntoView({ behavior: "smooth", block: "center" });
+      else window.scrollTo({ top: Math.max(0, c.region.y - 120), left: Math.max(0, c.region.x - 120), behavior: "smooth" });
+      this.position();
+      return;
+    }
     if (!pin || pin.classList.contains("detached")) return;
     for (const p of this.pins.values()) p.classList.remove("active");
     pin.classList.add("active");
@@ -2395,9 +2631,10 @@ var LoupeApp = class {
     if (elx) elx.scrollIntoView({ behavior: "smooth", block: "center" });
   }
   destroy() {
-    this.setInspecting(false);
+    this.setMode("off");
     this.mo?.disconnect();
     if (this.tick) clearInterval(this.tick);
+    window.clearTimeout(this.regionTimer);
     document.removeEventListener("keydown", this.onKey, true);
     this.root?.remove();
   }
@@ -2414,6 +2651,23 @@ function sep() {
 function clamp(n) {
   return Math.max(0, Math.min(1, n));
 }
+var REGION_ICON = `<svg class="ico" width="15" height="15" viewBox="0 0 15 15" fill="none" aria-hidden="true"><rect x="1.5" y="2.5" width="12" height="10" rx="1.5" stroke="currentColor" stroke-width="1.4" stroke-dasharray="2.4 1.8"/></svg>`;
+function regionAnchor(region) {
+  return {
+    tag: "region",
+    cssPath: `region ${Math.round(region.w)}\xD7${Math.round(region.h)}`,
+    xpath: "",
+    testid: null,
+    text: "",
+    attrs: {},
+    nthOfType: 1,
+    rect: { x: Math.round(region.x), y: Math.round(region.y), w: Math.round(region.w), h: Math.round(region.h) },
+    viewport: { w: window.innerWidth, h: window.innerHeight }
+  };
+}
+function regionNote(region) {
+  return `<!-- Loupe free-region annotation: ${Math.round(region.w)}\xD7${Math.round(region.h)}px at document (${Math.round(region.x)}, ${Math.round(region.y)}). No single DOM element \u2014 see the attached screenshot. -->`;
+}
 function describe(elx) {
   const testid = elx.getAttribute("data-testid") || elx.getAttribute("data-test");
   const tag = elx.tagName.toLowerCase();