@mahmulp/feedback-sdk 0.1.0 → 0.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Machmul Pratama
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Machmul Pratama
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,110 +1,111 @@
-# @mahmulp/feedback-sdk
-
-[![npm](https://img.shields.io/npm/v/@mahmulp/feedback-sdk.svg)](https://www.npmjs.com/package/@mahmulp/feedback-sdk)
-[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@mahmulp/feedback-sdk)](https://bundlephobia.com/package/@mahmulp/feedback-sdk)
-
-Framework-agnostic visual feedback SDK for prototype review. Reviewers pin comments to UI elements; you get back a stable DOM selector, percentage + pixel coordinates, viewport metadata, and an optional screenshot.
-
-Designed for **self-hosted** setups: pair this SDK with a backend (we ship one in the same repo) and own your data.
-
-- Floating launcher widget built in (toggle feedback mode, hide pins, hide launcher)
-- Stable DOM selectors that survive layout changes
-- Drag-to-move pins with optimistic update
-- Optional screenshot capture (via dynamically loaded `html2canvas`)
-- Svelte adapter for ergonomic SvelteKit integration
-- Works in React, Vue, and plain HTML via the same core API
-
-## Install
-
-```bash
-npm  install @mahmulp/feedback-sdk
-bun  add     @mahmulp/feedback-sdk
-pnpm add     @mahmulp/feedback-sdk
-yarn add     @mahmulp/feedback-sdk
-```
-
-## Quick start
-
-You always need an `apiUrl` and an `apiKey`. The key tells the API which project this prototype belongs to — generate one in your dashboard's project settings.
-
-### Vanilla / React / Vue
-
-```ts
-import { initFeedback } from '@mahmulp/feedback-sdk'
-
-initFeedback({
-  apiUrl: 'https://feedback.example.com',
-  apiKey: 'mp_…',
-})
-```
-
-That's it. A floating launcher appears in the bottom-right corner.
-
-### Svelte / SvelteKit
-
-```svelte
-<script lang="ts">
-  import { feedback } from '@mahmulp/feedback-sdk/svelte'
-</script>
-
-<div use:feedback={{
-  apiUrl: 'https://feedback.example.com',
-  apiKey: 'mp_…',
-}}>
-  <slot />
-</div>
-```
-
-### Local development without a backend
-
-For demos, e2e tests, or styling work — use the in-memory mock transport:
-
-```ts
-import { initFeedback } from '@mahmulp/feedback-sdk'
-import { createMockTransport } from '@mahmulp/feedback-sdk/mock'
-
-initFeedback({ transport: createMockTransport() })
-```
-
-## What it does
-
-When the user enters feedback mode (via the launcher or `setEnabled(true)`):
-
-- **Hover** any element → outline highlight + tag/class HUD.
-- **Click** → composer popover (name, email, comment, optional screenshot).
-- **Alt-click** → walks one parent up so you can pin a coarser element.
-- **Esc** → cancel.
-
-Existing pins are rendered as draggable markers. Click a pin to open its thread, reply, or change status. Drop a `data-feedback-id="some-key"` attribute on important elements to make their selectors human-readable and refactor-proof.
-
-## Public API
-
-```ts
-import {
-  initFeedback,
-  setFeedbackEnabled,
-  destroyFeedback,
-  resolveSelector,
-  findElement,
-  createHttpTransport,
-  captureViewport,
-} from '@mahmulp/feedback-sdk'
-```
-
-```ts
-import { feedback, feedbackEnabled } from '@mahmulp/feedback-sdk/svelte'
-```
-
-```ts
-import { createMockTransport } from '@mahmulp/feedback-sdk/mock'
-```
-
-The full set of options is documented in `InitFeedbackOptions` (TypeScript types ship with the package).
-
-## Self-host the backend
-
-The SDK pairs with a small self-hostable backend (Hono on Bun + PostgreSQL or in-memory store) that lives in the same monorepo: <https://github.com/MahmulP/feedback-prototype>. The dashboard there manages users, projects, and per-project API keys.
-
-## License
-
-MIT © Mahmul Pratama
+# @mahmulp/feedback-sdk
+
+[![npm](https://img.shields.io/npm/v/@mahmulp/feedback-sdk.svg)](https://www.npmjs.com/package/@mahmulp/feedback-sdk)
+[![types](https://img.shields.io/npm/types/@mahmulp/feedback-sdk.svg)](https://www.npmjs.com/package/@mahmulp/feedback-sdk)
+[![license](https://img.shields.io/npm/l/@mahmulp/feedback-sdk.svg)](./LICENSE)
+
+Framework-agnostic visual feedback SDK for prototype review. Reviewers pin comments to UI elements; you get back a stable DOM selector, percentage + pixel coordinates, viewport metadata, and an optional screenshot.
+
+Designed for **self-hosted** setups: pair this SDK with a backend (we ship one in the same repo) and own your data.
+
+- Floating launcher widget built in (toggle feedback mode, hide pins, hide launcher)
+- Stable DOM selectors that survive layout changes
+- Drag-to-move pins with optimistic update
+- Screenshot capture via dynamically loaded `html2canvas-pro` (bundled as a direct dependency)
+- Svelte adapter for ergonomic SvelteKit integration
+- Works in React, Vue, and plain HTML via the same core API
+
+## Install
+
+```bash
+npm  install @mahmulp/feedback-sdk
+bun  add     @mahmulp/feedback-sdk
+pnpm add     @mahmulp/feedback-sdk
+yarn add     @mahmulp/feedback-sdk
+```
+
+## Quick start
+
+You always need an `apiUrl` and an `apiKey`. The key tells the API which project this prototype belongs to — generate one in your dashboard's project settings.
+
+### Vanilla / React / Vue
+
+```ts
+import { initFeedback } from '@mahmulp/feedback-sdk'
+
+initFeedback({
+  apiUrl: 'https://feedback.example.com',
+  apiKey: 'mp_…',
+})
+```
+
+That's it. A floating launcher appears in the bottom-right corner.
+
+### Svelte / SvelteKit
+
+```svelte
+<script lang="ts">
+  import { feedback } from '@mahmulp/feedback-sdk/svelte'
+</script>
+
+<div use:feedback={{
+  apiUrl: 'https://feedback.example.com',
+  apiKey: 'mp_…',
+}}>
+  <slot />
+</div>
+```
+
+### Local development without a backend
+
+For demos, e2e tests, or styling work — use the in-memory mock transport:
+
+```ts
+import { initFeedback } from '@mahmulp/feedback-sdk'
+import { createMockTransport } from '@mahmulp/feedback-sdk/mock'
+
+initFeedback({ transport: createMockTransport() })
+```
+
+## What it does
+
+When the user enters feedback mode (via the launcher or `setEnabled(true)`):
+
+- **Hover** any element → outline highlight + tag/class HUD.
+- **Click** → composer popover (name, email, comment, optional screenshot).
+- **Alt-click** → walks one parent up so you can pin a coarser element.
+- **Esc** → cancel.
+
+Existing pins are rendered as draggable markers. Click a pin to open its thread, reply, or change status. Drop a `data-feedback-id="some-key"` attribute on important elements to make their selectors human-readable and refactor-proof.
+
+## Public API
+
+```ts
+import {
+  initFeedback,
+  setFeedbackEnabled,
+  destroyFeedback,
+  resolveSelector,
+  findElement,
+  createHttpTransport,
+  captureViewport,
+} from '@mahmulp/feedback-sdk'
+```
+
+```ts
+import { feedback, feedbackEnabled } from '@mahmulp/feedback-sdk/svelte'
+```
+
+```ts
+import { createMockTransport } from '@mahmulp/feedback-sdk/mock'
+```
+
+The full set of options is documented in `InitFeedbackOptions` (TypeScript types ship with the package).
+
+## Self-host the backend
+
+The SDK pairs with a small self-hostable backend (Hono on Bun + PostgreSQL or in-memory store) that lives in the same monorepo: <https://github.com/MahmulP/feedback-prototype>. The dashboard there manages users, projects, and per-project API keys.
+
+## License
+
+MIT © Mahmul Pratama

package/dist/index.cjs

@@ -184,7 +184,10 @@ var LauncherManager = class {
     __publicField(this, "state", {
       enabled: false,
       pinsVisible: true,
-      launcherVisible: true
+      // Start collapsed — only the small reveal bubble is visible until the
+      // user clicks it. Less visual weight on the prototype out of the box;
+      // user opts in by clicking the bubble icon in the bottom-right.
+      launcherVisible: false
     });
     this.launcherEl = document.createElement("div");
     this.launcherEl.className = "launcher";
@@ -236,6 +239,7 @@ var LauncherManager = class {
   /** True when an event originated from the launcher's own UI. */
   ownsNode(node) {
     if (!node) return false;
+    if (typeof Node === "undefined" || !(node instanceof Node)) return false;
     return this.launcherEl.contains(node) || this.revealEl.contains(node);
   }
   destroy() {
@@ -317,11 +321,34 @@ var PopoverManager = class {
     });
     return el;
   }
+  /** True when a thread for this feedback is already open. */
+  isThreadOpenFor(feedbackId) {
+    return this.current?.type === "thread" && this.current.feedbackId === feedbackId;
+  }
   showThread(feedback, anchor, cb) {
+    if (this.current?.type === "thread" && this.current.feedbackId === feedback.id) {
+      const fresh = this.buildThread(feedback, cb);
+      this.current.el.replaceWith(fresh);
+      this.current = {
+        type: "thread",
+        el: fresh,
+        pageX: anchor.pageX,
+        pageY: anchor.pageY,
+        feedbackId: feedback.id
+      };
+      this.repositionInternal();
+      return fresh;
+    }
     this.hide();
     const el = this.buildThread(feedback, cb);
     this.layer.appendChild(el);
-    this.current = { type: "thread", el, pageX: anchor.pageX, pageY: anchor.pageY };
+    this.current = {
+      type: "thread",
+      el,
+      pageX: anchor.pageX,
+      pageY: anchor.pageY,
+      feedbackId: feedback.id
+    };
     this.repositionInternal();
     return el;
   }
@@ -1029,33 +1056,65 @@ var Overlay = class {
     });
   }
   layoutPins() {
-    const next = document.createDocumentFragment();
+    const existing = /* @__PURE__ */ new Map();
+    for (const node of Array.from(this.pinLayer.children)) {
+      const id = node.dataset.feedbackId;
+      if (id) existing.set(id, node);
+    }
+    const desiredOrder = [];
+    const seen = /* @__PURE__ */ new Set();
     for (const fb of this.pendingFeedback) {
+      seen.add(fb.id);
       const target = findElement(fb.selector);
       const projected = projectCoordinates(target, fb.coordinates);
-      const pin = document.createElement("button");
-      pin.type = "button";
-      const classes = ["pin"];
-      if (projected.orphaned) classes.push("orphaned");
-      if (fb.status === "resolved") classes.push("resolved");
-      if (fb.status === "archived") classes.push("archived");
-      pin.className = classes.join(" ");
-      pin.setAttribute("data-feedback-id", fb.id);
-      pin.setAttribute("aria-label", `Feedback ${fb.id}`);
-      pin.style.left = `${projected.x - window.scrollX}px`;
-      pin.style.top = `${projected.y - window.scrollY}px`;
-      const label = document.createElement("span");
-      label.textContent = String(fb.thread.length || 1);
-      pin.appendChild(label);
-      pin.addEventListener("click", (e) => {
-        e.stopPropagation();
-        if (this.draggingPin === fb.id) return;
-        this.onPinClick?.(fb);
-      });
-      this.attachDragHandlers(pin, fb);
-      next.appendChild(pin);
+      const left = `${projected.x - window.scrollX}px`;
+      const top = `${projected.y - window.scrollY}px`;
+      let pin = existing.get(fb.id);
+      if (pin) {
+        const classes = ["pin"];
+        if (projected.orphaned) classes.push("orphaned");
+        if (fb.status === "resolved") classes.push("resolved");
+        if (fb.status === "archived") classes.push("archived");
+        if (pin.classList.contains("dragging")) classes.push("dragging");
+        pin.className = classes.join(" ");
+        if (pin.style.left !== left) pin.style.left = left;
+        if (pin.style.top !== top) pin.style.top = top;
+        const label = pin.firstElementChild;
+        const nextLabel = String(fb.thread.length || 1);
+        if (label && label.textContent !== nextLabel) label.textContent = nextLabel;
+      } else {
+        pin = document.createElement("button");
+        pin.type = "button";
+        const classes = ["pin"];
+        if (projected.orphaned) classes.push("orphaned");
+        if (fb.status === "resolved") classes.push("resolved");
+        if (fb.status === "archived") classes.push("archived");
+        pin.className = classes.join(" ");
+        pin.dataset.feedbackId = fb.id;
+        pin.setAttribute("aria-label", `Feedback ${fb.id}`);
+        pin.style.left = left;
+        pin.style.top = top;
+        const label = document.createElement("span");
+        label.textContent = String(fb.thread.length || 1);
+        pin.appendChild(label);
+        pin.addEventListener("click", (e) => {
+          e.stopPropagation();
+          if (this.draggingPin === fb.id) return;
+          const fresh = this.pendingFeedback.find((f) => f.id === fb.id) ?? fb;
+          this.onPinClick?.(fresh);
+        });
+        this.attachDragHandlers(pin, fb);
+      }
+      desiredOrder.push(pin);
+    }
+    for (const [id, node] of existing) {
+      if (!seen.has(id)) node.remove();
+    }
+    for (let i = 0; i < desiredOrder.length; i++) {
+      const want = desiredOrder[i];
+      const have = this.pinLayer.children[i];
+      if (have !== want) this.pinLayer.insertBefore(want, have ?? null);
     }
-    this.pinLayer.replaceChildren(next);
   }
   destroy() {
     if (this.rafHandle !== null) {
@@ -1174,8 +1233,6 @@ async function captureViewport(options = {}) {
   const html2canvas = await loadHtml2Canvas();
   if (!html2canvas) return null;
   const host = document.querySelector(`[${HOST_ATTR2}]`);
-  const previousVisibility = host?.style.visibility ?? "";
-  if (host) host.style.visibility = "hidden";
   try {
     const canvas = await html2canvas(document.documentElement, {
       backgroundColor: null,
@@ -1188,23 +1245,37 @@ async function captureViewport(options = {}) {
       windowHeight: window.innerHeight,
       logging: false,
       useCORS: true,
-      allowTaint: false
+      allowTaint: false,
+      ignoreElements: (el) => {
+        if (host && (el === host || host.contains(el))) return true;
+        if (el instanceof HTMLElement && el.hasAttribute(HOST_ATTR2)) return true;
+        return false;
+      }
     });
     return await canvasToBlob(canvas, opts.mimeType, opts.quality);
-  } catch {
+  } catch (err) {
+    if (typeof console !== "undefined") {
+      console.warn("[feedback-sdk] screenshot capture failed:", err);
+    }
     return null;
-  } finally {
-    if (host) host.style.visibility = previousVisibility;
   }
 }
 var html2canvasPromise = null;
+var html2canvasMissingWarned = false;
 async function loadHtml2Canvas() {
   if (html2canvasPromise) return html2canvasPromise;
   html2canvasPromise = (async () => {
     try {
-      const mod = await import('html2canvas');
+      const mod = await import('html2canvas-pro');
       return mod.default ?? mod ?? null;
-    } catch {
+    } catch (err) {
+      if (!html2canvasMissingWarned && typeof console !== "undefined") {
+        html2canvasMissingWarned = true;
+        console.warn(
+          "[feedback-sdk] screenshot capture disabled: failed to load `html2canvas-pro`. This shouldn't normally happen \u2014 html2canvas-pro is a direct dependency of the SDK. Pass `captureScreenshots: false` to silence this warning if intended.",
+          err
+        );
+      }
       return null;
     }
   })();
@@ -1497,8 +1568,6 @@ function initFeedback(options) {
           const updated = await transport.reply(fb.id, { author, body });
           setAuthor(author);
           replaceFeedback(updated);
-          overlay.popoverManager().hide();
-          activeThreadId = null;
           openThread(updated);
         } catch (err) {
           reportError(err);
@@ -1508,8 +1577,6 @@ function initFeedback(options) {
         try {
           const updated = await transport.setStatus(fb.id, status);
           replaceFeedback(updated);
-          overlay.popoverManager().hide();
-          activeThreadId = null;
           openThread(updated);
         } catch (err) {
           reportError(err);
@@ -1557,7 +1624,8 @@ function initFeedback(options) {
   }
   async function refresh() {
     try {
-      const result = await transport.list({ projectId: "" });
+      const pageUrl = getPageUrl();
+      const result = await transport.list({ projectId: "", pageUrl });
       state.feedbacks = result.items;
       overlay.renderPins(state.feedbacks, openThread, onPinDragEnd);
     } catch (err) {
@@ -1587,12 +1655,35 @@ function initFeedback(options) {
   document.addEventListener("keydown", onKeyDown, true);
   window.addEventListener("scroll", onWindowReposition, true);
   window.addEventListener("resize", onWindowReposition);
+  let lastSeenUrl = getPageUrl();
+  function onMaybeNavigate() {
+    const next = getPageUrl();
+    if (next === lastSeenUrl) return;
+    lastSeenUrl = next;
+    void refresh();
+  }
+  const originalPushState = history.pushState.bind(history);
+  const originalReplaceState = history.replaceState.bind(history);
+  history.pushState = function patchedPushState(...args) {
+    const result = originalPushState(...args);
+    queueMicrotask(onMaybeNavigate);
+    return result;
+  };
+  history.replaceState = function patchedReplaceState(...args) {
+    const result = originalReplaceState(...args);
+    queueMicrotask(onMaybeNavigate);
+    return result;
+  };
+  window.addEventListener("popstate", onMaybeNavigate);
   void refresh();
   overlay.setEnabledStyles(state.enabled);
   const wantsLauncher = options.showLauncher !== false;
   const launcherState = {
     pinsVisible: options.pinsVisible !== false,
-    launcherVisible: true
+    // Default to a collapsed launcher. The user reveals it by clicking the
+    // small bubble button in the bottom-right corner. This keeps the SDK's
+    // visual footprint near zero on first paint of the prototype.
+    launcherVisible: false
   };
   overlay.setPinsVisible(launcherState.pinsVisible);
   function syncLauncher() {
@@ -1649,6 +1740,9 @@ function initFeedback(options) {
       document.removeEventListener("keydown", onKeyDown, true);
       window.removeEventListener("scroll", onWindowReposition, true);
       window.removeEventListener("resize", onWindowReposition);
+      window.removeEventListener("popstate", onMaybeNavigate);
+      history.pushState = originalPushState;
+      history.replaceState = originalReplaceState;
       overlay.destroy();
     }
   };